Edit on GitHub

Expressions

Every AST node in SQLGlot is represented by a subclass of Expression.

This module contains the implementation of all supported Expression types. Additionally, it exposes a number of helper functions, which are mainly used to programmatically build SQL expressions, such as sqlglot.expressions.select.


   1"""
   2## Expressions
   3
   4Every AST node in SQLGlot is represented by a subclass of `Expression`.
   5
   6This module contains the implementation of all supported `Expression` types. Additionally,
   7it exposes a number of helper functions, which are mainly used to programmatically build
   8SQL expressions, such as `sqlglot.expressions.select`.
   9
  10----
  11"""
  12
  13from __future__ import annotations
  14
  15import datetime
  16import math
  17import numbers
  18import re
  19import typing as t
  20from collections import deque
  21from copy import deepcopy
  22from enum import auto
  23
  24from sqlglot.errors import ParseError
  25from sqlglot.helper import (
  26    AutoName,
  27    camel_to_snake_case,
  28    ensure_collection,
  29    seq_get,
  30    split_num_words,
  31    subclasses,
  32)
  33from sqlglot.tokens import Token
  34
  35if t.TYPE_CHECKING:
  36    from sqlglot.dialects.dialect import DialectType
  37
  38
  39class _Expression(type):
  40    def __new__(cls, clsname, bases, attrs):
  41        klass = super().__new__(cls, clsname, bases, attrs)
  42
  43        # When an Expression class is created, its key is automatically set to be
  44        # the lowercase version of the class' name.
  45        klass.key = clsname.lower()
  46
  47        # This is so that docstrings are not inherited in pdoc
  48        klass.__doc__ = klass.__doc__ or ""
  49
  50        return klass
  51
  52
  53class Expression(metaclass=_Expression):
  54    """
  55    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
  56    context, such as its child expressions, their names (arg keys), and whether a given child expression
  57    is optional or not.
  58
  59    Attributes:
  60        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
  61            and representing expressions as strings.
  62        arg_types: determines what arguments (child nodes) are supported by an expression. It
  63            maps arg keys to booleans that indicate whether the corresponding args are optional.
  64
  65    Example:
  66        >>> class Foo(Expression):
  67        ...     arg_types = {"this": True, "expression": False}
  68
  69        The above definition informs us that Foo is an Expression that requires an argument called
  70        "this" and may also optionally receive an argument called "expression".
  71
  72    Args:
  73        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  74        parent: a reference to the parent expression (or None, in case of root expressions).
  75        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
  76            uses to refer to it.
  77        comments: a list of comments that are associated with a given expression. This is used in
  78            order to preserve comments when transpiling SQL code.
  79        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
  80            optimizer, in order to enable some transformations that require type information.
  81    """
  82
  83    key = "expression"
  84    arg_types = {"this": True}
  85    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta")
  86
  87    def __init__(self, **args: t.Any):
  88        self.args: t.Dict[str, t.Any] = args
  89        self.parent: t.Optional[Expression] = None
  90        self.arg_key: t.Optional[str] = None
  91        self.comments: t.Optional[t.List[str]] = None
  92        self._type: t.Optional[DataType] = None
  93        self._meta: t.Optional[t.Dict[str, t.Any]] = None
  94
  95        for arg_key, value in self.args.items():
  96            self._set_parent(arg_key, value)
  97
  98    def __eq__(self, other) -> bool:
  99        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
 100
 101    def __hash__(self) -> int:
 102        return hash(
 103            (
 104                self.key,
 105                tuple(
 106                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
 107                ),
 108            )
 109        )
 110
 111    @property
 112    def this(self):
 113        """
 114        Retrieves the argument with key "this".
 115        """
 116        return self.args.get("this")
 117
 118    @property
 119    def expression(self):
 120        """
 121        Retrieves the argument with key "expression".
 122        """
 123        return self.args.get("expression")
 124
 125    @property
 126    def expressions(self):
 127        """
 128        Retrieves the argument with key "expressions".
 129        """
 130        return self.args.get("expressions") or []
 131
 132    def text(self, key) -> str:
 133        """
 134        Returns a textual representation of the argument corresponding to "key". This can only be used
 135        for args that are strings or leaf Expression instances, such as identifiers and literals.
 136        """
 137        field = self.args.get(key)
 138        if isinstance(field, str):
 139            return field
 140        if isinstance(field, (Identifier, Literal, Var)):
 141            return field.this
 142        if isinstance(field, (Star, Null)):
 143            return field.name
 144        return ""
 145
 146    @property
 147    def is_string(self) -> bool:
 148        """
 149        Checks whether a Literal expression is a string.
 150        """
 151        return isinstance(self, Literal) and self.args["is_string"]
 152
 153    @property
 154    def is_number(self) -> bool:
 155        """
 156        Checks whether a Literal expression is a number.
 157        """
 158        return isinstance(self, Literal) and not self.args["is_string"]
 159
 160    @property
 161    def is_int(self) -> bool:
 162        """
 163        Checks whether a Literal expression is an integer.
 164        """
 165        if self.is_number:
 166            try:
 167                int(self.name)
 168                return True
 169            except ValueError:
 170                pass
 171        return False
 172
 173    @property
 174    def is_star(self) -> bool:
 175        """Checks whether an expression is a star."""
 176        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
 177
 178    @property
 179    def alias(self) -> str:
 180        """
 181        Returns the alias of the expression, or an empty string if it's not aliased.
 182        """
 183        if isinstance(self.args.get("alias"), TableAlias):
 184            return self.args["alias"].name
 185        return self.text("alias")
 186
 187    @property
 188    def name(self) -> str:
 189        return self.text("this")
 190
 191    @property
 192    def alias_or_name(self):
 193        return self.alias or self.name
 194
 195    @property
 196    def output_name(self):
 197        """
 198        Name of the output column if this expression is a selection.
 199
 200        If the Expression has no output name, an empty string is returned.
 201
 202        Example:
 203            >>> from sqlglot import parse_one
 204            >>> parse_one("SELECT a").expressions[0].output_name
 205            'a'
 206            >>> parse_one("SELECT b AS c").expressions[0].output_name
 207            'c'
 208            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
 209            ''
 210        """
 211        return ""
 212
 213    @property
 214    def type(self) -> t.Optional[DataType]:
 215        return self._type
 216
 217    @type.setter
 218    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
 219        if dtype and not isinstance(dtype, DataType):
 220            dtype = DataType.build(dtype)
 221        self._type = dtype  # type: ignore
 222
 223    @property
 224    def meta(self) -> t.Dict[str, t.Any]:
 225        if self._meta is None:
 226            self._meta = {}
 227        return self._meta
 228
 229    def __deepcopy__(self, memo):
 230        copy = self.__class__(**deepcopy(self.args))
 231        if self.comments is not None:
 232            copy.comments = deepcopy(self.comments)
 233
 234        if self._type is not None:
 235            copy._type = self._type.copy()
 236
 237        if self._meta is not None:
 238            copy._meta = deepcopy(self._meta)
 239
 240        return copy
 241
 242    def copy(self):
 243        """
 244        Returns a deep copy of the expression.
 245        """
 246        new = deepcopy(self)
 247        new.parent = self.parent
 248        for item, parent, _ in new.bfs():
 249            if isinstance(item, Expression) and parent:
 250                item.parent = parent
 251        return new
 252
 253    def append(self, arg_key, value):
 254        """
 255        Appends value to arg_key if it's a list or sets it as a new list.
 256
 257        Args:
 258            arg_key (str): name of the list expression arg
 259            value (Any): value to append to the list
 260        """
 261        if not isinstance(self.args.get(arg_key), list):
 262            self.args[arg_key] = []
 263        self.args[arg_key].append(value)
 264        self._set_parent(arg_key, value)
 265
 266    def set(self, arg_key, value):
 267        """
 268        Sets `arg_key` to `value`.
 269
 270        Args:
 271            arg_key (str): name of the expression arg.
 272            value: value to set the arg to.
 273        """
 274        self.args[arg_key] = value
 275        self._set_parent(arg_key, value)
 276
 277    def _set_parent(self, arg_key, value):
 278        if isinstance(value, Expression):
 279            value.parent = self
 280            value.arg_key = arg_key
 281        elif isinstance(value, list):
 282            for v in value:
 283                if isinstance(v, Expression):
 284                    v.parent = self
 285                    v.arg_key = arg_key
 286
 287    @property
 288    def depth(self):
 289        """
 290        Returns the depth of this tree.
 291        """
 292        if self.parent:
 293            return self.parent.depth + 1
 294        return 0
 295
 296    def find(self, *expression_types, bfs=True):
 297        """
 298        Returns the first node in this tree which matches at least one of
 299        the specified types.
 300
 301        Args:
 302            expression_types (type): the expression type(s) to match.
 303
 304        Returns:
 305            The node which matches the criteria or None if no such node was found.
 306        """
 307        return next(self.find_all(*expression_types, bfs=bfs), None)
 308
 309    def find_all(self, *expression_types, bfs=True):
 310        """
 311        Returns a generator object which visits all nodes in this tree and only
 312        yields those that match at least one of the specified expression types.
 313
 314        Args:
 315            expression_types (type): the expression type(s) to match.
 316
 317        Returns:
 318            The generator object.
 319        """
 320        for expression, _, _ in self.walk(bfs=bfs):
 321            if isinstance(expression, expression_types):
 322                yield expression
 323
 324    def find_ancestor(self, *expression_types):
 325        """
 326        Returns a nearest parent matching expression_types.
 327
 328        Args:
 329            expression_types (type): the expression type(s) to match.
 330
 331        Returns:
 332            The parent node.
 333        """
 334        ancestor = self.parent
 335        while ancestor and not isinstance(ancestor, expression_types):
 336            ancestor = ancestor.parent
 337        return ancestor
 338
 339    @property
 340    def parent_select(self):
 341        """
 342        Returns the parent select statement.
 343        """
 344        return self.find_ancestor(Select)
 345
 346    def root(self) -> Expression:
 347        """
 348        Returns the root expression of this tree.
 349        """
 350        expression = self
 351        while expression.parent:
 352            expression = expression.parent
 353        return expression
 354
 355    def walk(self, bfs=True, prune=None):
 356        """
 357        Returns a generator object which visits all nodes in this tree.
 358
 359        Args:
 360            bfs (bool): if set to True the BFS traversal order will be applied,
 361                otherwise the DFS traversal will be used instead.
 362            prune ((node, parent, arg_key) -> bool): callable that returns True if
 363                the generator should stop traversing this branch of the tree.
 364
 365        Returns:
 366            the generator object.
 367        """
 368        if bfs:
 369            yield from self.bfs(prune=prune)
 370        else:
 371            yield from self.dfs(prune=prune)
 372
 373    def dfs(self, parent=None, key=None, prune=None):
 374        """
 375        Returns a generator object which visits all nodes in this tree in
 376        the DFS (Depth-first) order.
 377
 378        Returns:
 379            The generator object.
 380        """
 381        parent = parent or self.parent
 382        yield self, parent, key
 383        if prune and prune(self, parent, key):
 384            return
 385
 386        for k, v in self.args.items():
 387            for node in ensure_collection(v):
 388                if isinstance(node, Expression):
 389                    yield from node.dfs(self, k, prune)
 390
 391    def bfs(self, prune=None):
 392        """
 393        Returns a generator object which visits all nodes in this tree in
 394        the BFS (Breadth-first) order.
 395
 396        Returns:
 397            The generator object.
 398        """
 399        queue = deque([(self, self.parent, None)])
 400
 401        while queue:
 402            item, parent, key = queue.popleft()
 403
 404            yield item, parent, key
 405            if prune and prune(item, parent, key):
 406                continue
 407
 408            if isinstance(item, Expression):
 409                for k, v in item.args.items():
 410                    for node in ensure_collection(v):
 411                        if isinstance(node, Expression):
 412                            queue.append((node, item, k))
 413
 414    def unnest(self):
 415        """
 416        Returns the first non parenthesis child or self.
 417        """
 418        expression = self
 419        while isinstance(expression, Paren):
 420            expression = expression.this
 421        return expression
 422
 423    def unalias(self):
 424        """
 425        Returns the inner expression if this is an Alias.
 426        """
 427        if isinstance(self, Alias):
 428            return self.this
 429        return self
 430
 431    def unnest_operands(self):
 432        """
 433        Returns unnested operands as a tuple.
 434        """
 435        return tuple(arg.unnest() for arg in self.args.values() if arg)
 436
 437    def flatten(self, unnest=True):
 438        """
 439        Returns a generator which yields child nodes who's parents are the same class.
 440
 441        A AND B AND C -> [A, B, C]
 442        """
 443        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
 444            if not isinstance(node, self.__class__):
 445                yield node.unnest() if unnest else node
 446
 447    def __str__(self):
 448        return self.sql()
 449
 450    def __repr__(self):
 451        return self._to_s()
 452
 453    def sql(self, dialect: DialectType = None, **opts) -> str:
 454        """
 455        Returns SQL string representation of this tree.
 456
 457        Args:
 458            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
 459            opts: other `sqlglot.generator.Generator` options.
 460
 461        Returns:
 462            The SQL string.
 463        """
 464        from sqlglot.dialects import Dialect
 465
 466        return Dialect.get_or_raise(dialect)().generate(self, **opts)
 467
 468    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
 469        indent = "" if not level else "\n"
 470        indent += "".join(["  "] * level)
 471        left = f"({self.key.upper()} "
 472
 473        args: t.Dict[str, t.Any] = {
 474            k: ", ".join(
 475                v._to_s(hide_missing=hide_missing, level=level + 1)
 476                if hasattr(v, "_to_s")
 477                else str(v)
 478                for v in ensure_collection(vs)
 479                if v is not None
 480            )
 481            for k, vs in self.args.items()
 482        }
 483        args["comments"] = self.comments
 484        args["type"] = self.type
 485        args = {k: v for k, v in args.items() if v or not hide_missing}
 486
 487        right = ", ".join(f"{k}: {v}" for k, v in args.items())
 488        right += ")"
 489
 490        return indent + left + right
 491
 492    def transform(self, fun, *args, copy=True, **kwargs):
 493        """
 494        Recursively visits all tree nodes (excluding already transformed ones)
 495        and applies the given transformation function to each node.
 496
 497        Args:
 498            fun (function): a function which takes a node as an argument and returns a
 499                new transformed node or the same node without modifications. If the function
 500                returns None, then the corresponding node will be removed from the syntax tree.
 501            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
 502                modified in place.
 503
 504        Returns:
 505            The transformed tree.
 506        """
 507        node = self.copy() if copy else self
 508        new_node = fun(node, *args, **kwargs)
 509
 510        if new_node is None or not isinstance(new_node, Expression):
 511            return new_node
 512        if new_node is not node:
 513            new_node.parent = node.parent
 514            return new_node
 515
 516        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
 517        return new_node
 518
 519    def replace(self, expression):
 520        """
 521        Swap out this expression with a new expression.
 522
 523        For example::
 524
 525            >>> tree = Select().select("x").from_("tbl")
 526            >>> tree.find(Column).replace(Column(this="y"))
 527            (COLUMN this: y)
 528            >>> tree.sql()
 529            'SELECT y FROM tbl'
 530
 531        Args:
 532            expression (Expression|None): new node
 533
 534        Returns:
 535            The new expression or expressions.
 536        """
 537        if not self.parent:
 538            return expression
 539
 540        parent = self.parent
 541        self.parent = None
 542
 543        replace_children(parent, lambda child: expression if child is self else child)
 544        return expression
 545
 546    def pop(self):
 547        """
 548        Remove this expression from its AST.
 549        """
 550        self.replace(None)
 551
 552    def assert_is(self, type_):
 553        """
 554        Assert that this `Expression` is an instance of `type_`.
 555
 556        If it is NOT an instance of `type_`, this raises an assertion error.
 557        Otherwise, this returns this expression.
 558
 559        Examples:
 560            This is useful for type security in chained expressions:
 561
 562            >>> import sqlglot
 563            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
 564            'SELECT x, z FROM y'
 565        """
 566        assert isinstance(self, type_)
 567        return self
 568
 569    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
 570        """
 571        Checks if this expression is valid (e.g. all mandatory args are set).
 572
 573        Args:
 574            args: a sequence of values that were used to instantiate a Func expression. This is used
 575                to check that the provided arguments don't exceed the function argument limit.
 576
 577        Returns:
 578            A list of error messages for all possible errors that were found.
 579        """
 580        errors: t.List[str] = []
 581
 582        for k in self.args:
 583            if k not in self.arg_types:
 584                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
 585        for k, mandatory in self.arg_types.items():
 586            v = self.args.get(k)
 587            if mandatory and (v is None or (isinstance(v, list) and not v)):
 588                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
 589
 590        if (
 591            args
 592            and isinstance(self, Func)
 593            and len(args) > len(self.arg_types)
 594            and not self.is_var_len_args
 595        ):
 596            errors.append(
 597                f"The number of provided arguments ({len(args)}) is greater than "
 598                f"the maximum number of supported arguments ({len(self.arg_types)})"
 599            )
 600
 601        return errors
 602
 603    def dump(self):
 604        """
 605        Dump this Expression to a JSON-serializable dict.
 606        """
 607        from sqlglot.serde import dump
 608
 609        return dump(self)
 610
 611    @classmethod
 612    def load(cls, obj):
 613        """
 614        Load a dict (as returned by `Expression.dump`) into an Expression instance.
 615        """
 616        from sqlglot.serde import load
 617
 618        return load(obj)
 619
 620
 621IntoType = t.Union[
 622    str,
 623    t.Type[Expression],
 624    t.Collection[t.Union[str, t.Type[Expression]]],
 625]
 626
 627
 628class Condition(Expression):
 629    def and_(self, *expressions, dialect=None, **opts):
 630        """
 631        AND this condition with one or multiple expressions.
 632
 633        Example:
 634            >>> condition("x=1").and_("y=1").sql()
 635            'x = 1 AND y = 1'
 636
 637        Args:
 638            *expressions (str | Expression): the SQL code strings to parse.
 639                If an `Expression` instance is passed, it will be used as-is.
 640            dialect (str): the dialect used to parse the input expression.
 641            opts (kwargs): other options to use to parse the input expressions.
 642
 643        Returns:
 644            And: the new condition.
 645        """
 646        return and_(self, *expressions, dialect=dialect, **opts)
 647
 648    def or_(self, *expressions, dialect=None, **opts):
 649        """
 650        OR this condition with one or multiple expressions.
 651
 652        Example:
 653            >>> condition("x=1").or_("y=1").sql()
 654            'x = 1 OR y = 1'
 655
 656        Args:
 657            *expressions (str | Expression): the SQL code strings to parse.
 658                If an `Expression` instance is passed, it will be used as-is.
 659            dialect (str): the dialect used to parse the input expression.
 660            opts (kwargs): other options to use to parse the input expressions.
 661
 662        Returns:
 663            Or: the new condition.
 664        """
 665        return or_(self, *expressions, dialect=dialect, **opts)
 666
 667    def not_(self):
 668        """
 669        Wrap this condition with NOT.
 670
 671        Example:
 672            >>> condition("x=1").not_().sql()
 673            'NOT x = 1'
 674
 675        Returns:
 676            Not: the new condition.
 677        """
 678        return not_(self)
 679
 680
 681class Predicate(Condition):
 682    """Relationships like x = y, x > 1, x >= y."""
 683
 684
 685class DerivedTable(Expression):
 686    @property
 687    def alias_column_names(self):
 688        table_alias = self.args.get("alias")
 689        if not table_alias:
 690            return []
 691        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
 692        return [c.name for c in column_list]
 693
 694    @property
 695    def selects(self):
 696        alias = self.args.get("alias")
 697
 698        if alias:
 699            return alias.columns
 700        return []
 701
 702    @property
 703    def named_selects(self):
 704        return [select.output_name for select in self.selects]
 705
 706
 707class Unionable(Expression):
 708    def union(self, expression, distinct=True, dialect=None, **opts):
 709        """
 710        Builds a UNION expression.
 711
 712        Example:
 713            >>> import sqlglot
 714            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
 715            'SELECT * FROM foo UNION SELECT * FROM bla'
 716
 717        Args:
 718            expression (str | Expression): the SQL code string.
 719                If an `Expression` instance is passed, it will be used as-is.
 720            distinct (bool): set the DISTINCT flag if and only if this is true.
 721            dialect (str): the dialect used to parse the input expression.
 722            opts (kwargs): other options to use to parse the input expressions.
 723        Returns:
 724            Union: the Union expression.
 725        """
 726        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 727
 728    def intersect(self, expression, distinct=True, dialect=None, **opts):
 729        """
 730        Builds an INTERSECT expression.
 731
 732        Example:
 733            >>> import sqlglot
 734            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
 735            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
 736
 737        Args:
 738            expression (str | Expression): the SQL code string.
 739                If an `Expression` instance is passed, it will be used as-is.
 740            distinct (bool): set the DISTINCT flag if and only if this is true.
 741            dialect (str): the dialect used to parse the input expression.
 742            opts (kwargs): other options to use to parse the input expressions.
 743        Returns:
 744            Intersect: the Intersect expression
 745        """
 746        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 747
 748    def except_(self, expression, distinct=True, dialect=None, **opts):
 749        """
 750        Builds an EXCEPT expression.
 751
 752        Example:
 753            >>> import sqlglot
 754            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
 755            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
 756
 757        Args:
 758            expression (str | Expression): the SQL code string.
 759                If an `Expression` instance is passed, it will be used as-is.
 760            distinct (bool): set the DISTINCT flag if and only if this is true.
 761            dialect (str): the dialect used to parse the input expression.
 762            opts (kwargs): other options to use to parse the input expressions.
 763        Returns:
 764            Except: the Except expression
 765        """
 766        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
 767
 768
 769class UDTF(DerivedTable, Unionable):
 770    pass
 771
 772
 773class Cache(Expression):
 774    arg_types = {
 775        "with": False,
 776        "this": True,
 777        "lazy": False,
 778        "options": False,
 779        "expression": False,
 780    }
 781
 782
 783class Uncache(Expression):
 784    arg_types = {"this": True, "exists": False}
 785
 786
 787class Create(Expression):
 788    arg_types = {
 789        "with": False,
 790        "this": True,
 791        "kind": True,
 792        "expression": False,
 793        "exists": False,
 794        "properties": False,
 795        "replace": False,
 796        "unique": False,
 797        "indexes": False,
 798        "no_schema_binding": False,
 799        "begin": False,
 800    }
 801
 802
 803class Describe(Expression):
 804    arg_types = {"this": True, "kind": False}
 805
 806
 807class Set(Expression):
 808    arg_types = {"expressions": True}
 809
 810
 811class SetItem(Expression):
 812    arg_types = {
 813        "this": False,
 814        "expressions": False,
 815        "kind": False,
 816        "collate": False,  # MySQL SET NAMES statement
 817        "global": False,
 818    }
 819
 820
 821class Show(Expression):
 822    arg_types = {
 823        "this": True,
 824        "target": False,
 825        "offset": False,
 826        "limit": False,
 827        "like": False,
 828        "where": False,
 829        "db": False,
 830        "full": False,
 831        "mutex": False,
 832        "query": False,
 833        "channel": False,
 834        "global": False,
 835        "log": False,
 836        "position": False,
 837        "types": False,
 838    }
 839
 840
 841class UserDefinedFunction(Expression):
 842    arg_types = {"this": True, "expressions": False, "wrapped": False}
 843
 844
 845class CharacterSet(Expression):
 846    arg_types = {"this": True, "default": False}
 847
 848
 849class With(Expression):
 850    arg_types = {"expressions": True, "recursive": False}
 851
 852    @property
 853    def recursive(self) -> bool:
 854        return bool(self.args.get("recursive"))
 855
 856
 857class WithinGroup(Expression):
 858    arg_types = {"this": True, "expression": False}
 859
 860
 861class CTE(DerivedTable):
 862    arg_types = {"this": True, "alias": True}
 863
 864
 865class TableAlias(Expression):
 866    arg_types = {"this": False, "columns": False}
 867
 868    @property
 869    def columns(self):
 870        return self.args.get("columns") or []
 871
 872
 873class BitString(Condition):
 874    pass
 875
 876
 877class HexString(Condition):
 878    pass
 879
 880
 881class ByteString(Condition):
 882    pass
 883
 884
 885class Column(Condition):
 886    arg_types = {"this": True, "table": False, "db": False, "catalog": False}
 887
 888    @property
 889    def table(self) -> str:
 890        return self.text("table")
 891
 892    @property
 893    def db(self) -> str:
 894        return self.text("db")
 895
 896    @property
 897    def catalog(self) -> str:
 898        return self.text("catalog")
 899
 900    @property
 901    def output_name(self) -> str:
 902        return self.name
 903
 904
 905class ColumnDef(Expression):
 906    arg_types = {
 907        "this": True,
 908        "kind": False,
 909        "constraints": False,
 910        "exists": False,
 911    }
 912
 913
 914class AlterColumn(Expression):
 915    arg_types = {
 916        "this": True,
 917        "dtype": False,
 918        "collate": False,
 919        "using": False,
 920        "default": False,
 921        "drop": False,
 922    }
 923
 924
 925class RenameTable(Expression):
 926    pass
 927
 928
 929class ColumnConstraint(Expression):
 930    arg_types = {"this": False, "kind": True}
 931
 932
 933class ColumnConstraintKind(Expression):
 934    pass
 935
 936
 937class AutoIncrementColumnConstraint(ColumnConstraintKind):
 938    pass
 939
 940
 941class CaseSpecificColumnConstraint(ColumnConstraintKind):
 942    arg_types = {"not_": True}
 943
 944
 945class CharacterSetColumnConstraint(ColumnConstraintKind):
 946    arg_types = {"this": True}
 947
 948
 949class CheckColumnConstraint(ColumnConstraintKind):
 950    pass
 951
 952
 953class CollateColumnConstraint(ColumnConstraintKind):
 954    pass
 955
 956
 957class CommentColumnConstraint(ColumnConstraintKind):
 958    pass
 959
 960
 961class CompressColumnConstraint(ColumnConstraintKind):
 962    pass
 963
 964
 965class DateFormatColumnConstraint(ColumnConstraintKind):
 966    arg_types = {"this": True}
 967
 968
 969class DefaultColumnConstraint(ColumnConstraintKind):
 970    pass
 971
 972
 973class EncodeColumnConstraint(ColumnConstraintKind):
 974    pass
 975
 976
 977class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
 978    # this: True -> ALWAYS, this: False -> BY DEFAULT
 979    arg_types = {
 980        "this": False,
 981        "start": False,
 982        "increment": False,
 983        "minvalue": False,
 984        "maxvalue": False,
 985        "cycle": False,
 986    }
 987
 988
 989class InlineLengthColumnConstraint(ColumnConstraintKind):
 990    pass
 991
 992
 993class NotNullColumnConstraint(ColumnConstraintKind):
 994    arg_types = {"allow_null": False}
 995
 996
 997class PrimaryKeyColumnConstraint(ColumnConstraintKind):
 998    arg_types = {"desc": False}
 999
1000
1001class TitleColumnConstraint(ColumnConstraintKind):
1002    pass
1003
1004
1005class UniqueColumnConstraint(ColumnConstraintKind):
1006    arg_types: t.Dict[str, t.Any] = {}
1007
1008
1009class UppercaseColumnConstraint(ColumnConstraintKind):
1010    arg_types: t.Dict[str, t.Any] = {}
1011
1012
1013class PathColumnConstraint(ColumnConstraintKind):
1014    pass
1015
1016
1017class Constraint(Expression):
1018    arg_types = {"this": True, "expressions": True}
1019
1020
1021class Delete(Expression):
1022    arg_types = {"with": False, "this": False, "using": False, "where": False}
1023
1024
1025class Drop(Expression):
1026    arg_types = {
1027        "this": False,
1028        "kind": False,
1029        "exists": False,
1030        "temporary": False,
1031        "materialized": False,
1032        "cascade": False,
1033    }
1034
1035
1036class Filter(Expression):
1037    arg_types = {"this": True, "expression": True}
1038
1039
1040class Check(Expression):
1041    pass
1042
1043
1044class Directory(Expression):
1045    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1046    arg_types = {"this": True, "local": False, "row_format": False}
1047
1048
1049class ForeignKey(Expression):
1050    arg_types = {
1051        "expressions": True,
1052        "reference": False,
1053        "delete": False,
1054        "update": False,
1055    }
1056
1057
1058class PrimaryKey(Expression):
1059    arg_types = {"expressions": True, "options": False}
1060
1061
1062class Unique(Expression):
1063    arg_types = {"expressions": True}
1064
1065
1066# https://www.postgresql.org/docs/9.1/sql-selectinto.html
1067# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples
1068class Into(Expression):
1069    arg_types = {"this": True, "temporary": False, "unlogged": False}
1070
1071
1072class From(Expression):
1073    arg_types = {"expressions": True}
1074
1075
1076class Having(Expression):
1077    pass
1078
1079
1080class Hint(Expression):
1081    arg_types = {"expressions": True}
1082
1083
1084class JoinHint(Expression):
1085    arg_types = {"this": True, "expressions": True}
1086
1087
1088class Identifier(Expression):
1089    arg_types = {"this": True, "quoted": False}
1090
1091    @property
1092    def quoted(self):
1093        return bool(self.args.get("quoted"))
1094
1095    def __eq__(self, other):
1096        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1097
1098    def __hash__(self):
1099        return hash((self.key, self.this.lower()))
1100
1101    @property
1102    def output_name(self):
1103        return self.name
1104
1105
1106class Index(Expression):
1107    arg_types = {
1108        "this": False,
1109        "table": False,
1110        "where": False,
1111        "columns": False,
1112        "unique": False,
1113        "primary": False,
1114        "amp": False,  # teradata
1115    }
1116
1117
1118class Insert(Expression):
1119    arg_types = {
1120        "with": False,
1121        "this": True,
1122        "expression": False,
1123        "overwrite": False,
1124        "exists": False,
1125        "partition": False,
1126        "alternative": False,
1127    }
1128
1129
1130# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html
1131class Introducer(Expression):
1132    arg_types = {"this": True, "expression": True}
1133
1134
1135# national char, like n'utf8'
1136class National(Expression):
1137    pass
1138
1139
1140class LoadData(Expression):
1141    arg_types = {
1142        "this": True,
1143        "local": False,
1144        "overwrite": False,
1145        "inpath": True,
1146        "partition": False,
1147        "input_format": False,
1148        "serde": False,
1149    }
1150
1151
1152class Partition(Expression):
1153    arg_types = {"expressions": True}
1154
1155
1156class Fetch(Expression):
1157    arg_types = {"direction": False, "count": False}
1158
1159
1160class Group(Expression):
1161    arg_types = {
1162        "expressions": False,
1163        "grouping_sets": False,
1164        "cube": False,
1165        "rollup": False,
1166    }
1167
1168
1169class Lambda(Expression):
1170    arg_types = {"this": True, "expressions": True}
1171
1172
1173class Limit(Expression):
1174    arg_types = {"this": False, "expression": True}
1175
1176
1177class Literal(Condition):
1178    arg_types = {"this": True, "is_string": True}
1179
1180    def __eq__(self, other):
1181        return (
1182            isinstance(other, Literal)
1183            and self.this == other.this
1184            and self.args["is_string"] == other.args["is_string"]
1185        )
1186
1187    def __hash__(self):
1188        return hash((self.key, self.this, self.args["is_string"]))
1189
1190    @classmethod
1191    def number(cls, number) -> Literal:
1192        return cls(this=str(number), is_string=False)
1193
1194    @classmethod
1195    def string(cls, string) -> Literal:
1196        return cls(this=str(string), is_string=True)
1197
1198    @property
1199    def output_name(self):
1200        return self.name
1201
1202
1203class Join(Expression):
1204    arg_types = {
1205        "this": True,
1206        "on": False,
1207        "side": False,
1208        "kind": False,
1209        "using": False,
1210        "natural": False,
1211    }
1212
1213    @property
1214    def kind(self):
1215        return self.text("kind").upper()
1216
1217    @property
1218    def side(self):
1219        return self.text("side").upper()
1220
1221    @property
1222    def alias_or_name(self):
1223        return self.this.alias_or_name
1224
1225    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1226        """
1227        Append to or set the ON expressions.
1228
1229        Example:
1230            >>> import sqlglot
1231            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1232            'JOIN x ON y = 1'
1233
1234        Args:
1235            *expressions (str | Expression): the SQL code strings to parse.
1236                If an `Expression` instance is passed, it will be used as-is.
1237                Multiple expressions are combined with an AND operator.
1238            append (bool): if `True`, AND the new expressions to any existing expression.
1239                Otherwise, this resets the expression.
1240            dialect (str): the dialect used to parse the input expressions.
1241            copy (bool): if `False`, modify this expression instance in-place.
1242            opts (kwargs): other options to use to parse the input expressions.
1243
1244        Returns:
1245            Join: the modified join expression.
1246        """
1247        join = _apply_conjunction_builder(
1248            *expressions,
1249            instance=self,
1250            arg="on",
1251            append=append,
1252            dialect=dialect,
1253            copy=copy,
1254            **opts,
1255        )
1256
1257        if join.kind == "CROSS":
1258            join.set("kind", None)
1259
1260        return join
1261
1262    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1263        """
1264        Append to or set the USING expressions.
1265
1266        Example:
1267            >>> import sqlglot
1268            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1269            'JOIN x USING (foo, bla)'
1270
1271        Args:
1272            *expressions (str | Expression): the SQL code strings to parse.
1273                If an `Expression` instance is passed, it will be used as-is.
1274            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1275                Otherwise, this resets the expression.
1276            dialect (str): the dialect used to parse the input expressions.
1277            copy (bool): if `False`, modify this expression instance in-place.
1278            opts (kwargs): other options to use to parse the input expressions.
1279
1280        Returns:
1281            Join: the modified join expression.
1282        """
1283        join = _apply_list_builder(
1284            *expressions,
1285            instance=self,
1286            arg="using",
1287            append=append,
1288            dialect=dialect,
1289            copy=copy,
1290            **opts,
1291        )
1292
1293        if join.kind == "CROSS":
1294            join.set("kind", None)
1295
1296        return join
1297
1298
1299class Lateral(UDTF):
1300    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
1301
1302
1303class MatchRecognize(Expression):
1304    arg_types = {
1305        "partition_by": False,
1306        "order": False,
1307        "measures": False,
1308        "rows": False,
1309        "after": False,
1310        "pattern": False,
1311        "define": False,
1312    }
1313
1314
1315# Clickhouse FROM FINAL modifier
1316# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier
1317class Final(Expression):
1318    pass
1319
1320
1321class Offset(Expression):
1322    arg_types = {"this": False, "expression": True}
1323
1324
1325class Order(Expression):
1326    arg_types = {"this": False, "expressions": True}
1327
1328
1329# hive specific sorts
1330# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy
1331class Cluster(Order):
1332    pass
1333
1334
1335class Distribute(Order):
1336    pass
1337
1338
1339class Sort(Order):
1340    pass
1341
1342
1343class Ordered(Expression):
1344    arg_types = {"this": True, "desc": True, "nulls_first": True}
1345
1346
1347class Property(Expression):
1348    arg_types = {"this": True, "value": True}
1349
1350
1351class AfterJournalProperty(Property):
1352    arg_types = {"no": True, "dual": False, "local": False}
1353
1354
1355class AlgorithmProperty(Property):
1356    arg_types = {"this": True}
1357
1358
1359class AutoIncrementProperty(Property):
1360    arg_types = {"this": True}
1361
1362
1363class BlockCompressionProperty(Property):
1364    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
1365
1366
1367class CharacterSetProperty(Property):
1368    arg_types = {"this": True, "default": True}
1369
1370
1371class ChecksumProperty(Property):
1372    arg_types = {"on": False, "default": False}
1373
1374
1375class CollateProperty(Property):
1376    arg_types = {"this": True}
1377
1378
1379class DataBlocksizeProperty(Property):
1380    arg_types = {"size": False, "units": False, "min": False, "default": False}
1381
1382
1383class DefinerProperty(Property):
1384    arg_types = {"this": True}
1385
1386
1387class DistKeyProperty(Property):
1388    arg_types = {"this": True}
1389
1390
1391class DistStyleProperty(Property):
1392    arg_types = {"this": True}
1393
1394
1395class EngineProperty(Property):
1396    arg_types = {"this": True}
1397
1398
1399class ExecuteAsProperty(Property):
1400    arg_types = {"this": True}
1401
1402
1403class ExternalProperty(Property):
1404    arg_types = {"this": False}
1405
1406
1407class FallbackProperty(Property):
1408    arg_types = {"no": True, "protection": False}
1409
1410
1411class FileFormatProperty(Property):
1412    arg_types = {"this": True}
1413
1414
1415class FreespaceProperty(Property):
1416    arg_types = {"this": True, "percent": False}
1417
1418
1419class IsolatedLoadingProperty(Property):
1420    arg_types = {
1421        "no": True,
1422        "concurrent": True,
1423        "for_all": True,
1424        "for_insert": True,
1425        "for_none": True,
1426    }
1427
1428
1429class JournalProperty(Property):
1430    arg_types = {"no": True, "dual": False, "before": False}
1431
1432
1433class LanguageProperty(Property):
1434    arg_types = {"this": True}
1435
1436
1437class LikeProperty(Property):
1438    arg_types = {"this": True, "expressions": False}
1439
1440
1441class LocationProperty(Property):
1442    arg_types = {"this": True}
1443
1444
1445class LockingProperty(Property):
1446    arg_types = {
1447        "this": False,
1448        "kind": True,
1449        "for_or_in": True,
1450        "lock_type": True,
1451        "override": False,
1452    }
1453
1454
1455class LogProperty(Property):
1456    arg_types = {"no": True}
1457
1458
1459class MaterializedProperty(Property):
1460    arg_types = {"this": False}
1461
1462
1463class MergeBlockRatioProperty(Property):
1464    arg_types = {"this": False, "no": False, "default": False, "percent": False}
1465
1466
1467class NoPrimaryIndexProperty(Property):
1468    arg_types = {"this": False}
1469
1470
1471class OnCommitProperty(Property):
1472    arg_type = {"this": False}
1473
1474
1475class PartitionedByProperty(Property):
1476    arg_types = {"this": True}
1477
1478
1479class ReturnsProperty(Property):
1480    arg_types = {"this": True, "is_table": False, "table": False}
1481
1482
1483class RowFormatDelimitedProperty(Property):
1484    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1485    arg_types = {
1486        "fields": False,
1487        "escaped": False,
1488        "collection_items": False,
1489        "map_keys": False,
1490        "lines": False,
1491        "null": False,
1492        "serde": False,
1493    }
1494
1495
1496class RowFormatSerdeProperty(Property):
1497    arg_types = {"this": True}
1498
1499
1500class SchemaCommentProperty(Property):
1501    arg_types = {"this": True}
1502
1503
1504class SerdeProperties(Property):
1505    arg_types = {"expressions": True}
1506
1507
1508class SetProperty(Property):
1509    arg_types = {"multi": True}
1510
1511
1512class SortKeyProperty(Property):
1513    arg_types = {"this": True, "compound": False}
1514
1515
1516class SqlSecurityProperty(Property):
1517    arg_types = {"definer": True}
1518
1519
1520class TableFormatProperty(Property):
1521    arg_types = {"this": True}
1522
1523
1524class TemporaryProperty(Property):
1525    arg_types = {"global_": True}
1526
1527
1528class TransientProperty(Property):
1529    arg_types = {"this": False}
1530
1531
1532class VolatilityProperty(Property):
1533    arg_types = {"this": True}
1534
1535
1536class WithDataProperty(Property):
1537    arg_types = {"no": True, "statistics": False}
1538
1539
1540class WithJournalTableProperty(Property):
1541    arg_types = {"this": True}
1542
1543
1544class Properties(Expression):
1545    arg_types = {"expressions": True}
1546
1547    NAME_TO_PROPERTY = {
1548        "ALGORITHM": AlgorithmProperty,
1549        "AUTO_INCREMENT": AutoIncrementProperty,
1550        "CHARACTER SET": CharacterSetProperty,
1551        "COLLATE": CollateProperty,
1552        "COMMENT": SchemaCommentProperty,
1553        "DEFINER": DefinerProperty,
1554        "DISTKEY": DistKeyProperty,
1555        "DISTSTYLE": DistStyleProperty,
1556        "ENGINE": EngineProperty,
1557        "EXECUTE AS": ExecuteAsProperty,
1558        "FORMAT": FileFormatProperty,
1559        "LANGUAGE": LanguageProperty,
1560        "LOCATION": LocationProperty,
1561        "PARTITIONED_BY": PartitionedByProperty,
1562        "RETURNS": ReturnsProperty,
1563        "SORTKEY": SortKeyProperty,
1564        "TABLE_FORMAT": TableFormatProperty,
1565    }
1566
1567    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1568
1569    # CREATE property locations
1570    # Form: schema specified
1571    #   create [POST_CREATE]
1572    #     table a [POST_NAME]
1573    #     (b int) [POST_SCHEMA]
1574    #     with ([POST_WITH])
1575    #     index (b) [POST_INDEX]
1576    #
1577    # Form: alias selection
1578    #   create [POST_CREATE]
1579    #     table a [POST_NAME]
1580    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
1581    #     index (c) [POST_INDEX]
1582    class Location(AutoName):
1583        POST_CREATE = auto()
1584        POST_NAME = auto()
1585        POST_SCHEMA = auto()
1586        POST_WITH = auto()
1587        POST_ALIAS = auto()
1588        POST_EXPRESSION = auto()
1589        POST_INDEX = auto()
1590        UNSUPPORTED = auto()
1591
1592    @classmethod
1593    def from_dict(cls, properties_dict) -> Properties:
1594        expressions = []
1595        for key, value in properties_dict.items():
1596            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1597            if property_cls:
1598                expressions.append(property_cls(this=convert(value)))
1599            else:
1600                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1601
1602        return cls(expressions=expressions)
1603
1604
1605class Qualify(Expression):
1606    pass
1607
1608
1609# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql
1610class Return(Expression):
1611    pass
1612
1613
1614class Reference(Expression):
1615    arg_types = {"this": True, "expressions": False, "options": False}
1616
1617
1618class Tuple(Expression):
1619    arg_types = {"expressions": False}
1620
1621
1622class Subqueryable(Unionable):
1623    def subquery(self, alias=None, copy=True) -> Subquery:
1624        """
1625        Convert this expression to an aliased expression that can be used as a Subquery.
1626
1627        Example:
1628            >>> subquery = Select().select("x").from_("tbl").subquery()
1629            >>> Select().select("x").from_(subquery).sql()
1630            'SELECT x FROM (SELECT x FROM tbl)'
1631
1632        Args:
1633            alias (str | Identifier): an optional alias for the subquery
1634            copy (bool): if `False`, modify this expression instance in-place.
1635
1636        Returns:
1637            Alias: the subquery
1638        """
1639        instance = _maybe_copy(self, copy)
1640        return Subquery(
1641            this=instance,
1642            alias=TableAlias(this=to_identifier(alias)),
1643        )
1644
1645    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1646        raise NotImplementedError
1647
1648    @property
1649    def ctes(self):
1650        with_ = self.args.get("with")
1651        if not with_:
1652            return []
1653        return with_.expressions
1654
1655    @property
1656    def selects(self):
1657        raise NotImplementedError("Subqueryable objects must implement `selects`")
1658
1659    @property
1660    def named_selects(self):
1661        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1662
1663    def with_(
1664        self,
1665        alias,
1666        as_,
1667        recursive=None,
1668        append=True,
1669        dialect=None,
1670        copy=True,
1671        **opts,
1672    ):
1673        """
1674        Append to or set the common table expressions.
1675
1676        Example:
1677            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1678            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1679
1680        Args:
1681            alias (str | Expression): the SQL code string to parse as the table name.
1682                If an `Expression` instance is passed, this is used as-is.
1683            as_ (str | Expression): the SQL code string to parse as the table expression.
1684                If an `Expression` instance is passed, it will be used as-is.
1685            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1686            append (bool): if `True`, add to any existing expressions.
1687                Otherwise, this resets the expressions.
1688            dialect (str): the dialect used to parse the input expression.
1689            copy (bool): if `False`, modify this expression instance in-place.
1690            opts (kwargs): other options to use to parse the input expressions.
1691
1692        Returns:
1693            Select: the modified expression.
1694        """
1695        alias_expression = maybe_parse(
1696            alias,
1697            dialect=dialect,
1698            into=TableAlias,
1699            **opts,
1700        )
1701        as_expression = maybe_parse(
1702            as_,
1703            dialect=dialect,
1704            **opts,
1705        )
1706        cte = CTE(
1707            this=as_expression,
1708            alias=alias_expression,
1709        )
1710        return _apply_child_list_builder(
1711            cte,
1712            instance=self,
1713            arg="with",
1714            append=append,
1715            copy=copy,
1716            into=With,
1717            properties={"recursive": recursive or False},
1718        )
1719
1720
1721QUERY_MODIFIERS = {
1722    "match": False,
1723    "laterals": False,
1724    "joins": False,
1725    "pivots": False,
1726    "where": False,
1727    "group": False,
1728    "having": False,
1729    "qualify": False,
1730    "windows": False,
1731    "distribute": False,
1732    "sort": False,
1733    "cluster": False,
1734    "order": False,
1735    "limit": False,
1736    "offset": False,
1737    "lock": False,
1738}
1739
1740
1741class Table(Expression):
1742    arg_types = {
1743        "this": True,
1744        "alias": False,
1745        "db": False,
1746        "catalog": False,
1747        "laterals": False,
1748        "joins": False,
1749        "pivots": False,
1750        "hints": False,
1751        "system_time": False,
1752    }
1753
1754    @property
1755    def db(self) -> str:
1756        return self.text("db")
1757
1758    @property
1759    def catalog(self) -> str:
1760        return self.text("catalog")
1761
1762
1763# See the TSQL "Querying data in a system-versioned temporal table" page
1764class SystemTime(Expression):
1765    arg_types = {
1766        "this": False,
1767        "expression": False,
1768        "kind": True,
1769    }
1770
1771
1772class Union(Subqueryable):
1773    arg_types = {
1774        "with": False,
1775        "this": True,
1776        "expression": True,
1777        "distinct": False,
1778        **QUERY_MODIFIERS,
1779    }
1780
1781    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1782        """
1783        Set the LIMIT expression.
1784
1785        Example:
1786            >>> select("1").union(select("1")).limit(1).sql()
1787            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1788
1789        Args:
1790            expression (str | int | Expression): the SQL code string to parse.
1791                This can also be an integer.
1792                If a `Limit` instance is passed, this is used as-is.
1793                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1794            dialect (str): the dialect used to parse the input expression.
1795            copy (bool): if `False`, modify this expression instance in-place.
1796            opts (kwargs): other options to use to parse the input expressions.
1797
1798        Returns:
1799            Select: The limited subqueryable.
1800        """
1801        return (
1802            select("*")
1803            .from_(self.subquery(alias="_l_0", copy=copy))
1804            .limit(expression, dialect=dialect, copy=False, **opts)
1805        )
1806
1807    def select(
1808        self,
1809        *expressions: str | Expression,
1810        append: bool = True,
1811        dialect: DialectType = None,
1812        copy: bool = True,
1813        **opts,
1814    ) -> Union:
1815        """Append to or set the SELECT of the union recursively.
1816
1817        Example:
1818            >>> from sqlglot import parse_one
1819            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1820            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1821
1822        Args:
1823            *expressions: the SQL code strings to parse.
1824                If an `Expression` instance is passed, it will be used as-is.
1825            append: if `True`, add to any existing expressions.
1826                Otherwise, this resets the expressions.
1827            dialect: the dialect used to parse the input expressions.
1828            copy: if `False`, modify this expression instance in-place.
1829            opts: other options to use to parse the input expressions.
1830
1831        Returns:
1832            Union: the modified expression.
1833        """
1834        this = self.copy() if copy else self
1835        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1836        this.expression.unnest().select(
1837            *expressions, append=append, dialect=dialect, copy=False, **opts
1838        )
1839        return this
1840
1841    @property
1842    def named_selects(self):
1843        return self.this.unnest().named_selects
1844
1845    @property
1846    def is_star(self) -> bool:
1847        return self.this.is_star or self.expression.is_star
1848
1849    @property
1850    def selects(self):
1851        return self.this.unnest().selects
1852
1853    @property
1854    def left(self):
1855        return self.this
1856
1857    @property
1858    def right(self):
1859        return self.expression
1860
1861
1862class Except(Union):
1863    pass
1864
1865
1866class Intersect(Union):
1867    pass
1868
1869
1870class Unnest(UDTF):
1871    arg_types = {
1872        "expressions": True,
1873        "ordinality": False,
1874        "alias": False,
1875        "offset": False,
1876    }
1877
1878
1879class Update(Expression):
1880    arg_types = {
1881        "with": False,
1882        "this": False,
1883        "expressions": True,
1884        "from": False,
1885        "where": False,
1886    }
1887
1888
1889class Values(UDTF):
1890    arg_types = {
1891        "expressions": True,
1892        "ordinality": False,
1893        "alias": False,
1894    }
1895
1896
1897class Var(Expression):
1898    pass
1899
1900
1901class Schema(Expression):
1902    arg_types = {"this": False, "expressions": False}
1903
1904
1905# Used to represent the FOR UPDATE and FOR SHARE locking read types.
1906# https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html
1907class Lock(Expression):
1908    arg_types = {"update": True}
1909
1910
1911class Select(Subqueryable):
1912    arg_types = {
1913        "with": False,
1914        "expressions": False,
1915        "hint": False,
1916        "distinct": False,
1917        "into": False,
1918        "from": False,
1919        **QUERY_MODIFIERS,
1920    }
1921
1922    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1923        """
1924        Set the FROM expression.
1925
1926        Example:
1927            >>> Select().from_("tbl").select("x").sql()
1928            'SELECT x FROM tbl'
1929
1930        Args:
1931            *expressions (str | Expression): the SQL code strings to parse.
1932                If a `From` instance is passed, this is used as-is.
1933                If another `Expression` instance is passed, it will be wrapped in a `From`.
1934            append (bool): if `True`, add to any existing expressions.
1935                Otherwise, this flattens all the `From` expression into a single expression.
1936            dialect (str): the dialect used to parse the input expression.
1937            copy (bool): if `False`, modify this expression instance in-place.
1938            opts (kwargs): other options to use to parse the input expressions.
1939
1940        Returns:
1941            Select: the modified expression.
1942        """
1943        return _apply_child_list_builder(
1944            *expressions,
1945            instance=self,
1946            arg="from",
1947            append=append,
1948            copy=copy,
1949            prefix="FROM",
1950            into=From,
1951            dialect=dialect,
1952            **opts,
1953        )
1954
1955    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1956        """
1957        Set the GROUP BY expression.
1958
1959        Example:
1960            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1961            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1962
1963        Args:
1964            *expressions (str | Expression): the SQL code strings to parse.
1965                If a `Group` instance is passed, this is used as-is.
1966                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1967                If nothing is passed in then a group by is not applied to the expression
1968            append (bool): if `True`, add to any existing expressions.
1969                Otherwise, this flattens all the `Group` expression into a single expression.
1970            dialect (str): the dialect used to parse the input expression.
1971            copy (bool): if `False`, modify this expression instance in-place.
1972            opts (kwargs): other options to use to parse the input expressions.
1973
1974        Returns:
1975            Select: the modified expression.
1976        """
1977        if not expressions:
1978            return self if not copy else self.copy()
1979        return _apply_child_list_builder(
1980            *expressions,
1981            instance=self,
1982            arg="group",
1983            append=append,
1984            copy=copy,
1985            prefix="GROUP BY",
1986            into=Group,
1987            dialect=dialect,
1988            **opts,
1989        )
1990
1991    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1992        """
1993        Set the ORDER BY expression.
1994
1995        Example:
1996            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1997            'SELECT x FROM tbl ORDER BY x DESC'
1998
1999        Args:
2000            *expressions (str | Expression): the SQL code strings to parse.
2001                If a `Group` instance is passed, this is used as-is.
2002                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2003            append (bool): if `True`, add to any existing expressions.
2004                Otherwise, this flattens all the `Order` expression into a single expression.
2005            dialect (str): the dialect used to parse the input expression.
2006            copy (bool): if `False`, modify this expression instance in-place.
2007            opts (kwargs): other options to use to parse the input expressions.
2008
2009        Returns:
2010            Select: the modified expression.
2011        """
2012        return _apply_child_list_builder(
2013            *expressions,
2014            instance=self,
2015            arg="order",
2016            append=append,
2017            copy=copy,
2018            prefix="ORDER BY",
2019            into=Order,
2020            dialect=dialect,
2021            **opts,
2022        )
2023
2024    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2025        """
2026        Set the SORT BY expression.
2027
2028        Example:
2029            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2030            'SELECT x FROM tbl SORT BY x DESC'
2031
2032        Args:
2033            *expressions (str | Expression): the SQL code strings to parse.
2034                If a `Group` instance is passed, this is used as-is.
2035                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2036            append (bool): if `True`, add to any existing expressions.
2037                Otherwise, this flattens all the `Order` expression into a single expression.
2038            dialect (str): the dialect used to parse the input expression.
2039            copy (bool): if `False`, modify this expression instance in-place.
2040            opts (kwargs): other options to use to parse the input expressions.
2041
2042        Returns:
2043            Select: the modified expression.
2044        """
2045        return _apply_child_list_builder(
2046            *expressions,
2047            instance=self,
2048            arg="sort",
2049            append=append,
2050            copy=copy,
2051            prefix="SORT BY",
2052            into=Sort,
2053            dialect=dialect,
2054            **opts,
2055        )
2056
2057    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2058        """
2059        Set the CLUSTER BY expression.
2060
2061        Example:
2062            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2063            'SELECT x FROM tbl CLUSTER BY x DESC'
2064
2065        Args:
2066            *expressions (str | Expression): the SQL code strings to parse.
2067                If a `Group` instance is passed, this is used as-is.
2068                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2069            append (bool): if `True`, add to any existing expressions.
2070                Otherwise, this flattens all the `Order` expression into a single expression.
2071            dialect (str): the dialect used to parse the input expression.
2072            copy (bool): if `False`, modify this expression instance in-place.
2073            opts (kwargs): other options to use to parse the input expressions.
2074
2075        Returns:
2076            Select: the modified expression.
2077        """
2078        return _apply_child_list_builder(
2079            *expressions,
2080            instance=self,
2081            arg="cluster",
2082            append=append,
2083            copy=copy,
2084            prefix="CLUSTER BY",
2085            into=Cluster,
2086            dialect=dialect,
2087            **opts,
2088        )
2089
2090    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2091        """
2092        Set the LIMIT expression.
2093
2094        Example:
2095            >>> Select().from_("tbl").select("x").limit(10).sql()
2096            'SELECT x FROM tbl LIMIT 10'
2097
2098        Args:
2099            expression (str | int | Expression): the SQL code string to parse.
2100                This can also be an integer.
2101                If a `Limit` instance is passed, this is used as-is.
2102                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2103            dialect (str): the dialect used to parse the input expression.
2104            copy (bool): if `False`, modify this expression instance in-place.
2105            opts (kwargs): other options to use to parse the input expressions.
2106
2107        Returns:
2108            Select: the modified expression.
2109        """
2110        return _apply_builder(
2111            expression=expression,
2112            instance=self,
2113            arg="limit",
2114            into=Limit,
2115            prefix="LIMIT",
2116            dialect=dialect,
2117            copy=copy,
2118            **opts,
2119        )
2120
2121    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2122        """
2123        Set the OFFSET expression.
2124
2125        Example:
2126            >>> Select().from_("tbl").select("x").offset(10).sql()
2127            'SELECT x FROM tbl OFFSET 10'
2128
2129        Args:
2130            expression (str | int | Expression): the SQL code string to parse.
2131                This can also be an integer.
2132                If a `Offset` instance is passed, this is used as-is.
2133                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2134            dialect (str): the dialect used to parse the input expression.
2135            copy (bool): if `False`, modify this expression instance in-place.
2136            opts (kwargs): other options to use to parse the input expressions.
2137
2138        Returns:
2139            Select: the modified expression.
2140        """
2141        return _apply_builder(
2142            expression=expression,
2143            instance=self,
2144            arg="offset",
2145            into=Offset,
2146            prefix="OFFSET",
2147            dialect=dialect,
2148            copy=copy,
2149            **opts,
2150        )
2151
2152    def select(
2153        self,
2154        *expressions: str | Expression,
2155        append: bool = True,
2156        dialect: DialectType = None,
2157        copy: bool = True,
2158        **opts,
2159    ) -> Select:
2160        """
2161        Append to or set the SELECT expressions.
2162
2163        Example:
2164            >>> Select().select("x", "y").sql()
2165            'SELECT x, y'
2166
2167        Args:
2168            *expressions: the SQL code strings to parse.
2169                If an `Expression` instance is passed, it will be used as-is.
2170            append: if `True`, add to any existing expressions.
2171                Otherwise, this resets the expressions.
2172            dialect: the dialect used to parse the input expressions.
2173            copy: if `False`, modify this expression instance in-place.
2174            opts: other options to use to parse the input expressions.
2175
2176        Returns:
2177            Select: the modified expression.
2178        """
2179        return _apply_list_builder(
2180            *expressions,
2181            instance=self,
2182            arg="expressions",
2183            append=append,
2184            dialect=dialect,
2185            copy=copy,
2186            **opts,
2187        )
2188
2189    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2190        """
2191        Append to or set the LATERAL expressions.
2192
2193        Example:
2194            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2195            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2196
2197        Args:
2198            *expressions (str | Expression): the SQL code strings to parse.
2199                If an `Expression` instance is passed, it will be used as-is.
2200            append (bool): if `True`, add to any existing expressions.
2201                Otherwise, this resets the expressions.
2202            dialect (str): the dialect used to parse the input expressions.
2203            copy (bool): if `False`, modify this expression instance in-place.
2204            opts (kwargs): other options to use to parse the input expressions.
2205
2206        Returns:
2207            Select: the modified expression.
2208        """
2209        return _apply_list_builder(
2210            *expressions,
2211            instance=self,
2212            arg="laterals",
2213            append=append,
2214            into=Lateral,
2215            prefix="LATERAL VIEW",
2216            dialect=dialect,
2217            copy=copy,
2218            **opts,
2219        )
2220
2221    def join(
2222        self,
2223        expression,
2224        on=None,
2225        using=None,
2226        append=True,
2227        join_type=None,
2228        join_alias=None,
2229        dialect=None,
2230        copy=True,
2231        **opts,
2232    ) -> Select:
2233        """
2234        Append to or set the JOIN expressions.
2235
2236        Example:
2237            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2238            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2239
2240            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2241            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2242
2243            Use `join_type` to change the type of join:
2244
2245            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2246            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2247
2248        Args:
2249            expression (str | Expression): the SQL code string to parse.
2250                If an `Expression` instance is passed, it will be used as-is.
2251            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2252                If an `Expression` instance is passed, it will be used as-is.
2253            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2254                If an `Expression` instance is passed, it will be used as-is.
2255            append (bool): if `True`, add to any existing expressions.
2256                Otherwise, this resets the expressions.
2257            join_type (str): If set, alter the parsed join type
2258            dialect (str): the dialect used to parse the input expressions.
2259            copy (bool): if `False`, modify this expression instance in-place.
2260            opts (kwargs): other options to use to parse the input expressions.
2261
2262        Returns:
2263            Select: the modified expression.
2264        """
2265        parse_args = {"dialect": dialect, **opts}
2266
2267        try:
2268            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2269        except ParseError:
2270            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2271
2272        join = expression if isinstance(expression, Join) else Join(this=expression)
2273
2274        if isinstance(join.this, Select):
2275            join.this.replace(join.this.subquery())
2276
2277        if join_type:
2278            natural: t.Optional[Token]
2279            side: t.Optional[Token]
2280            kind: t.Optional[Token]
2281
2282            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2283
2284            if natural:
2285                join.set("natural", True)
2286            if side:
2287                join.set("side", side.text)
2288            if kind:
2289                join.set("kind", kind.text)
2290
2291        if on:
2292            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2293            join.set("on", on)
2294
2295        if using:
2296            join = _apply_list_builder(
2297                *ensure_collection(using),
2298                instance=join,
2299                arg="using",
2300                append=append,
2301                copy=copy,
2302                **opts,
2303            )
2304
2305        if join_alias:
2306            join.set("this", alias_(join.this, join_alias, table=True))
2307        return _apply_list_builder(
2308            join,
2309            instance=self,
2310            arg="joins",
2311            append=append,
2312            copy=copy,
2313            **opts,
2314        )
2315
2316    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2317        """
2318        Append to or set the WHERE expressions.
2319
2320        Example:
2321            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2322            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2323
2324        Args:
2325            *expressions (str | Expression): the SQL code strings to parse.
2326                If an `Expression` instance is passed, it will be used as-is.
2327                Multiple expressions are combined with an AND operator.
2328            append (bool): if `True`, AND the new expressions to any existing expression.
2329                Otherwise, this resets the expression.
2330            dialect (str): the dialect used to parse the input expressions.
2331            copy (bool): if `False`, modify this expression instance in-place.
2332            opts (kwargs): other options to use to parse the input expressions.
2333
2334        Returns:
2335            Select: the modified expression.
2336        """
2337        return _apply_conjunction_builder(
2338            *expressions,
2339            instance=self,
2340            arg="where",
2341            append=append,
2342            into=Where,
2343            dialect=dialect,
2344            copy=copy,
2345            **opts,
2346        )
2347
2348    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2349        """
2350        Append to or set the HAVING expressions.
2351
2352        Example:
2353            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2354            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2355
2356        Args:
2357            *expressions (str | Expression): the SQL code strings to parse.
2358                If an `Expression` instance is passed, it will be used as-is.
2359                Multiple expressions are combined with an AND operator.
2360            append (bool): if `True`, AND the new expressions to any existing expression.
2361                Otherwise, this resets the expression.
2362            dialect (str): the dialect used to parse the input expressions.
2363            copy (bool): if `False`, modify this expression instance in-place.
2364            opts (kwargs): other options to use to parse the input expressions.
2365
2366        Returns:
2367            Select: the modified expression.
2368        """
2369        return _apply_conjunction_builder(
2370            *expressions,
2371            instance=self,
2372            arg="having",
2373            append=append,
2374            into=Having,
2375            dialect=dialect,
2376            copy=copy,
2377            **opts,
2378        )
2379
2380    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2381        return _apply_list_builder(
2382            *expressions,
2383            instance=self,
2384            arg="windows",
2385            append=append,
2386            into=Window,
2387            dialect=dialect,
2388            copy=copy,
2389            **opts,
2390        )
2391
2392    def distinct(self, distinct=True, copy=True) -> Select:
2393        """
2394        Set the OFFSET expression.
2395
2396        Example:
2397            >>> Select().from_("tbl").select("x").distinct().sql()
2398            'SELECT DISTINCT x FROM tbl'
2399
2400        Args:
2401            distinct (bool): whether the Select should be distinct
2402            copy (bool): if `False`, modify this expression instance in-place.
2403
2404        Returns:
2405            Select: the modified expression.
2406        """
2407        instance = _maybe_copy(self, copy)
2408        instance.set("distinct", Distinct() if distinct else None)
2409        return instance
2410
2411    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2412        """
2413        Convert this expression to a CREATE TABLE AS statement.
2414
2415        Example:
2416            >>> Select().select("*").from_("tbl").ctas("x").sql()
2417            'CREATE TABLE x AS SELECT * FROM tbl'
2418
2419        Args:
2420            table (str | Expression): the SQL code string to parse as the table name.
2421                If another `Expression` instance is passed, it will be used as-is.
2422            properties (dict): an optional mapping of table properties
2423            dialect (str): the dialect used to parse the input table.
2424            copy (bool): if `False`, modify this expression instance in-place.
2425            opts (kwargs): other options to use to parse the input table.
2426
2427        Returns:
2428            Create: the CREATE TABLE AS expression
2429        """
2430        instance = _maybe_copy(self, copy)
2431        table_expression = maybe_parse(
2432            table,
2433            into=Table,
2434            dialect=dialect,
2435            **opts,
2436        )
2437        properties_expression = None
2438        if properties:
2439            properties_expression = Properties.from_dict(properties)
2440
2441        return Create(
2442            this=table_expression,
2443            kind="table",
2444            expression=instance,
2445            properties=properties_expression,
2446        )
2447
2448    def lock(self, update: bool = True, copy: bool = True) -> Select:
2449        """
2450        Set the locking read mode for this expression.
2451
2452        Examples:
2453            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2454            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2455
2456            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2457            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2458
2459        Args:
2460            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2461            copy: if `False`, modify this expression instance in-place.
2462
2463        Returns:
2464            The modified expression.
2465        """
2466
2467        inst = _maybe_copy(self, copy)
2468        inst.set("lock", Lock(update=update))
2469
2470        return inst
2471
2472    @property
2473    def named_selects(self) -> t.List[str]:
2474        return [e.output_name for e in self.expressions if e.alias_or_name]
2475
2476    @property
2477    def is_star(self) -> bool:
2478        return any(expression.is_star for expression in self.expressions)
2479
2480    @property
2481    def selects(self) -> t.List[Expression]:
2482        return self.expressions
2483
2484
2485class Subquery(DerivedTable, Unionable):
2486    arg_types = {
2487        "this": True,
2488        "alias": False,
2489        "with": False,
2490        **QUERY_MODIFIERS,
2491    }
2492
2493    def unnest(self):
2494        """
2495        Returns the first non subquery.
2496        """
2497        expression = self
2498        while isinstance(expression, Subquery):
2499            expression = expression.this
2500        return expression
2501
2502    @property
2503    def is_star(self) -> bool:
2504        return self.this.is_star
2505
2506    @property
2507    def output_name(self):
2508        return self.alias
2509
2510
2511class TableSample(Expression):
2512    arg_types = {
2513        "this": False,
2514        "method": False,
2515        "bucket_numerator": False,
2516        "bucket_denominator": False,
2517        "bucket_field": False,
2518        "percent": False,
2519        "rows": False,
2520        "size": False,
2521        "seed": False,
2522    }
2523
2524
2525class Tag(Expression):
2526    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2527
2528    arg_types = {
2529        "this": False,
2530        "prefix": False,
2531        "postfix": False,
2532    }
2533
2534
2535class Pivot(Expression):
2536    arg_types = {
2537        "this": False,
2538        "alias": False,
2539        "expressions": True,
2540        "field": True,
2541        "unpivot": True,
2542    }
2543
2544
2545class Window(Expression):
2546    arg_types = {
2547        "this": True,
2548        "partition_by": False,
2549        "order": False,
2550        "spec": False,
2551        "alias": False,
2552    }
2553
2554
2555class WindowSpec(Expression):
2556    arg_types = {
2557        "kind": False,
2558        "start": False,
2559        "start_side": False,
2560        "end": False,
2561        "end_side": False,
2562    }
2563
2564
2565class Where(Expression):
2566    pass
2567
2568
2569class Star(Expression):
2570    arg_types = {"except": False, "replace": False}
2571
2572    @property
2573    def name(self) -> str:
2574        return "*"
2575
2576    @property
2577    def output_name(self):
2578        return self.name
2579
2580
2581class Parameter(Expression):
2582    arg_types = {"this": True, "wrapped": False}
2583
2584
2585class SessionParameter(Expression):
2586    arg_types = {"this": True, "kind": False}
2587
2588
2589class Placeholder(Expression):
2590    arg_types = {"this": False}
2591
2592
2593class Null(Condition):
2594    arg_types: t.Dict[str, t.Any] = {}
2595
2596    @property
2597    def name(self) -> str:
2598        return "NULL"
2599
2600
2601class Boolean(Condition):
2602    pass
2603
2604
2605class DataType(Expression):
2606    arg_types = {
2607        "this": True,
2608        "expressions": False,
2609        "nested": False,
2610        "values": False,
2611        "prefix": False,
2612    }
2613
2614    class Type(AutoName):
2615        CHAR = auto()
2616        NCHAR = auto()
2617        VARCHAR = auto()
2618        NVARCHAR = auto()
2619        TEXT = auto()
2620        MEDIUMTEXT = auto()
2621        LONGTEXT = auto()
2622        MEDIUMBLOB = auto()
2623        LONGBLOB = auto()
2624        BINARY = auto()
2625        VARBINARY = auto()
2626        INT = auto()
2627        TINYINT = auto()
2628        SMALLINT = auto()
2629        BIGINT = auto()
2630        FLOAT = auto()
2631        DOUBLE = auto()
2632        DECIMAL = auto()
2633        BOOLEAN = auto()
2634        JSON = auto()
2635        JSONB = auto()
2636        INTERVAL = auto()
2637        TIME = auto()
2638        TIMESTAMP = auto()
2639        TIMESTAMPTZ = auto()
2640        TIMESTAMPLTZ = auto()
2641        DATE = auto()
2642        DATETIME = auto()
2643        ARRAY = auto()
2644        MAP = auto()
2645        UUID = auto()
2646        GEOGRAPHY = auto()
2647        GEOMETRY = auto()
2648        STRUCT = auto()
2649        NULLABLE = auto()
2650        HLLSKETCH = auto()
2651        HSTORE = auto()
2652        SUPER = auto()
2653        SERIAL = auto()
2654        SMALLSERIAL = auto()
2655        BIGSERIAL = auto()
2656        XML = auto()
2657        UNIQUEIDENTIFIER = auto()
2658        MONEY = auto()
2659        SMALLMONEY = auto()
2660        ROWVERSION = auto()
2661        IMAGE = auto()
2662        VARIANT = auto()
2663        OBJECT = auto()
2664        INET = auto()
2665        NULL = auto()
2666        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2667
2668    TEXT_TYPES = {
2669        Type.CHAR,
2670        Type.NCHAR,
2671        Type.VARCHAR,
2672        Type.NVARCHAR,
2673        Type.TEXT,
2674    }
2675
2676    INTEGER_TYPES = {
2677        Type.INT,
2678        Type.TINYINT,
2679        Type.SMALLINT,
2680        Type.BIGINT,
2681    }
2682
2683    FLOAT_TYPES = {
2684        Type.FLOAT,
2685        Type.DOUBLE,
2686    }
2687
2688    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2689
2690    TEMPORAL_TYPES = {
2691        Type.TIMESTAMP,
2692        Type.TIMESTAMPTZ,
2693        Type.TIMESTAMPLTZ,
2694        Type.DATE,
2695        Type.DATETIME,
2696    }
2697
2698    @classmethod
2699    def build(
2700        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2701    ) -> DataType:
2702        from sqlglot import parse_one
2703
2704        if isinstance(dtype, str):
2705            if dtype.upper() in cls.Type.__members__:
2706                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2707            else:
2708                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2709            if data_type_exp is None:
2710                raise ValueError(f"Unparsable data type value: {dtype}")
2711        elif isinstance(dtype, DataType.Type):
2712            data_type_exp = DataType(this=dtype)
2713        elif isinstance(dtype, DataType):
2714            return dtype
2715        else:
2716            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2717        return DataType(**{**data_type_exp.args, **kwargs})
2718
2719    def is_type(self, dtype: DataType.Type) -> bool:
2720        return self.this == dtype
2721
2722
2723# https://www.postgresql.org/docs/15/datatype-pseudo.html
2724class PseudoType(Expression):
2725    pass
2726
2727
2728class StructKwarg(Expression):
2729    arg_types = {"this": True, "expression": True}
2730
2731
2732# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...)
2733class SubqueryPredicate(Predicate):
2734    pass
2735
2736
2737class All(SubqueryPredicate):
2738    pass
2739
2740
2741class Any(SubqueryPredicate):
2742    pass
2743
2744
2745class Exists(SubqueryPredicate):
2746    pass
2747
2748
2749# Commands to interact with the databases or engines. For most of the command
2750# expressions we parse whatever comes after the command's name as a string.
2751class Command(Expression):
2752    arg_types = {"this": True, "expression": False}
2753
2754
2755class Transaction(Expression):
2756    arg_types = {"this": False, "modes": False}
2757
2758
2759class Commit(Expression):
2760    arg_types = {"chain": False}
2761
2762
2763class Rollback(Expression):
2764    arg_types = {"savepoint": False}
2765
2766
2767class AlterTable(Expression):
2768    arg_types = {"this": True, "actions": True, "exists": False}
2769
2770
2771class AddConstraint(Expression):
2772    arg_types = {"this": False, "expression": False, "enforced": False}
2773
2774
2775class DropPartition(Expression):
2776    arg_types = {"expressions": True, "exists": False}
2777
2778
2779# Binary expressions like (ADD a b)
2780class Binary(Expression):
2781    arg_types = {"this": True, "expression": True}
2782
2783    @property
2784    def left(self):
2785        return self.this
2786
2787    @property
2788    def right(self):
2789        return self.expression
2790
2791
2792class Add(Binary):
2793    pass
2794
2795
2796class Connector(Binary, Condition):
2797    pass
2798
2799
2800class And(Connector):
2801    pass
2802
2803
2804class Or(Connector):
2805    pass
2806
2807
2808class BitwiseAnd(Binary):
2809    pass
2810
2811
2812class BitwiseLeftShift(Binary):
2813    pass
2814
2815
2816class BitwiseOr(Binary):
2817    pass
2818
2819
2820class BitwiseRightShift(Binary):
2821    pass
2822
2823
2824class BitwiseXor(Binary):
2825    pass
2826
2827
2828class Div(Binary):
2829    pass
2830
2831
2832class Dot(Binary):
2833    @property
2834    def name(self) -> str:
2835        return self.expression.name
2836
2837
2838class DPipe(Binary):
2839    pass
2840
2841
2842class EQ(Binary, Predicate):
2843    pass
2844
2845
2846class NullSafeEQ(Binary, Predicate):
2847    pass
2848
2849
2850class NullSafeNEQ(Binary, Predicate):
2851    pass
2852
2853
2854class Distance(Binary):
2855    pass
2856
2857
2858class Escape(Binary):
2859    pass
2860
2861
2862class Glob(Binary, Predicate):
2863    pass
2864
2865
2866class GT(Binary, Predicate):
2867    pass
2868
2869
2870class GTE(Binary, Predicate):
2871    pass
2872
2873
2874class ILike(Binary, Predicate):
2875    pass
2876
2877
2878class ILikeAny(Binary, Predicate):
2879    pass
2880
2881
2882class IntDiv(Binary):
2883    pass
2884
2885
2886class Is(Binary, Predicate):
2887    pass
2888
2889
2890class Kwarg(Binary):
2891    """Kwarg in special functions like func(kwarg => y)."""
2892
2893
2894class Like(Binary, Predicate):
2895    pass
2896
2897
2898class LikeAny(Binary, Predicate):
2899    pass
2900
2901
2902class LT(Binary, Predicate):
2903    pass
2904
2905
2906class LTE(Binary, Predicate):
2907    pass
2908
2909
2910class Mod(Binary):
2911    pass
2912
2913
2914class Mul(Binary):
2915    pass
2916
2917
2918class NEQ(Binary, Predicate):
2919    pass
2920
2921
2922class SimilarTo(Binary, Predicate):
2923    pass
2924
2925
2926class Slice(Binary):
2927    arg_types = {"this": False, "expression": False}
2928
2929
2930class Sub(Binary):
2931    pass
2932
2933
2934# Unary Expressions
2935# (NOT a)
2936class Unary(Expression):
2937    pass
2938
2939
2940class BitwiseNot(Unary):
2941    pass
2942
2943
2944class Not(Unary, Condition):
2945    pass
2946
2947
2948class Paren(Unary, Condition):
2949    arg_types = {"this": True, "with": False}
2950
2951
2952class Neg(Unary):
2953    pass
2954
2955
2956# Special Functions
2957class Alias(Expression):
2958    arg_types = {"this": True, "alias": False}
2959
2960    @property
2961    def output_name(self):
2962        return self.alias
2963
2964
2965class Aliases(Expression):
2966    arg_types = {"this": True, "expressions": True}
2967
2968    @property
2969    def aliases(self):
2970        return self.expressions
2971
2972
2973class AtTimeZone(Expression):
2974    arg_types = {"this": True, "zone": True}
2975
2976
2977class Between(Predicate):
2978    arg_types = {"this": True, "low": True, "high": True}
2979
2980
2981class Bracket(Condition):
2982    arg_types = {"this": True, "expressions": True}
2983
2984
2985class Distinct(Expression):
2986    arg_types = {"expressions": False, "on": False}
2987
2988
2989class In(Predicate):
2990    arg_types = {
2991        "this": True,
2992        "expressions": False,
2993        "query": False,
2994        "unnest": False,
2995        "field": False,
2996        "is_global": False,
2997    }
2998
2999
3000class TimeUnit(Expression):
3001    """Automatically converts unit arg into a var."""
3002
3003    arg_types = {"unit": False}
3004
3005    def __init__(self, **args):
3006        unit = args.get("unit")
3007        if isinstance(unit, Column):
3008            args["unit"] = Var(this=unit.name)
3009        elif isinstance(unit, Week):
3010            unit.set("this", Var(this=unit.this.name))
3011        super().__init__(**args)
3012
3013
3014class Interval(TimeUnit):
3015    arg_types = {"this": False, "unit": False}
3016
3017
3018class IgnoreNulls(Expression):
3019    pass
3020
3021
3022class RespectNulls(Expression):
3023    pass
3024
3025
3026# Functions
3027class Func(Condition):
3028    """
3029    The base class for all function expressions.
3030
3031    Attributes:
3032        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
3033            treated as a variable length argument and the argument's value will be stored as a list.
3034        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
3035            for this function expression. These values are used to map this node to a name during parsing
3036            as well as to provide the function's name during SQL string generation. By default the SQL
3037            name is set to the expression's class name transformed to snake case.
3038    """
3039
3040    is_var_len_args = False
3041
3042    @classmethod
3043    def from_arg_list(cls, args):
3044        if cls.is_var_len_args:
3045            all_arg_keys = list(cls.arg_types)
3046            # If this function supports variable length argument treat the last argument as such.
3047            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3048            num_non_var = len(non_var_len_arg_keys)
3049
3050            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3051            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3052        else:
3053            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3054
3055        return cls(**args_dict)
3056
3057    @classmethod
3058    def sql_names(cls):
3059        if cls is Func:
3060            raise NotImplementedError(
3061                "SQL name is only supported by concrete function implementations"
3062            )
3063        if "_sql_names" not in cls.__dict__:
3064            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3065        return cls._sql_names
3066
3067    @classmethod
3068    def sql_name(cls):
3069        return cls.sql_names()[0]
3070
3071    @classmethod
3072    def default_parser_mappings(cls):
3073        return {name: cls.from_arg_list for name in cls.sql_names()}
3074
3075
3076class AggFunc(Func):
3077    pass
3078
3079
3080class Abs(Func):
3081    pass
3082
3083
3084class Anonymous(Func):
3085    arg_types = {"this": True, "expressions": False}
3086    is_var_len_args = True
3087
3088
3089class ApproxDistinct(AggFunc):
3090    arg_types = {"this": True, "accuracy": False}
3091
3092
3093class Array(Func):
3094    arg_types = {"expressions": False}
3095    is_var_len_args = True
3096
3097
3098class GenerateSeries(Func):
3099    arg_types = {"start": True, "end": True, "step": False}
3100
3101
3102class ArrayAgg(AggFunc):
3103    pass
3104
3105
3106class ArrayAll(Func):
3107    arg_types = {"this": True, "expression": True}
3108
3109
3110class ArrayAny(Func):
3111    arg_types = {"this": True, "expression": True}
3112
3113
3114class ArrayConcat(Func):
3115    arg_types = {"this": True, "expressions": False}
3116    is_var_len_args = True
3117
3118
3119class ArrayContains(Func):
3120    arg_types = {"this": True, "expression": True}
3121
3122
3123class ArrayFilter(Func):
3124    arg_types = {"this": True, "expression": True}
3125    _sql_names = ["FILTER", "ARRAY_FILTER"]
3126
3127
3128class ArraySize(Func):
3129    arg_types = {"this": True, "expression": False}
3130
3131
3132class ArraySort(Func):
3133    arg_types = {"this": True, "expression": False}
3134
3135
3136class ArraySum(Func):
3137    pass
3138
3139
3140class ArrayUnionAgg(AggFunc):
3141    pass
3142
3143
3144class Avg(AggFunc):
3145    pass
3146
3147
3148class AnyValue(AggFunc):
3149    pass
3150
3151
3152class Case(Func):
3153    arg_types = {"this": False, "ifs": True, "default": False}
3154
3155
3156class Cast(Func):
3157    arg_types = {"this": True, "to": True}
3158
3159    @property
3160    def name(self) -> str:
3161        return self.this.name
3162
3163    @property
3164    def to(self):
3165        return self.args["to"]
3166
3167    @property
3168    def output_name(self):
3169        return self.name
3170
3171    def is_type(self, dtype: DataType.Type) -> bool:
3172        return self.to.is_type(dtype)
3173
3174
3175class Collate(Binary):
3176    pass
3177
3178
3179class TryCast(Cast):
3180    pass
3181
3182
3183class Ceil(Func):
3184    arg_types = {"this": True, "decimals": False}
3185    _sql_names = ["CEIL", "CEILING"]
3186
3187
3188class Coalesce(Func):
3189    arg_types = {"this": True, "expressions": False}
3190    is_var_len_args = True
3191
3192
3193class Concat(Func):
3194    arg_types = {"expressions": True}
3195    is_var_len_args = True
3196
3197
3198class ConcatWs(Concat):
3199    _sql_names = ["CONCAT_WS"]
3200
3201
3202class Count(AggFunc):
3203    arg_types = {"this": False}
3204
3205
3206class CurrentDate(Func):
3207    arg_types = {"this": False}
3208
3209
3210class CurrentDatetime(Func):
3211    arg_types = {"this": False}
3212
3213
3214class CurrentTime(Func):
3215    arg_types = {"this": False}
3216
3217
3218class CurrentTimestamp(Func):
3219    arg_types = {"this": False}
3220
3221
3222class DateAdd(Func, TimeUnit):
3223    arg_types = {"this": True, "expression": True, "unit": False}
3224
3225
3226class DateSub(Func, TimeUnit):
3227    arg_types = {"this": True, "expression": True, "unit": False}
3228
3229
3230class DateDiff(Func, TimeUnit):
3231    arg_types = {"this": True, "expression": True, "unit": False}
3232
3233
3234class DateTrunc(Func):
3235    arg_types = {"unit": True, "this": True, "zone": False}
3236
3237
3238class DatetimeAdd(Func, TimeUnit):
3239    arg_types = {"this": True, "expression": True, "unit": False}
3240
3241
3242class DatetimeSub(Func, TimeUnit):
3243    arg_types = {"this": True, "expression": True, "unit": False}
3244
3245
3246class DatetimeDiff(Func, TimeUnit):
3247    arg_types = {"this": True, "expression": True, "unit": False}
3248
3249
3250class DatetimeTrunc(Func, TimeUnit):
3251    arg_types = {"this": True, "unit": True, "zone": False}
3252
3253
3254class DayOfWeek(Func):
3255    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
3256
3257
3258class DayOfMonth(Func):
3259    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
3260
3261
3262class DayOfYear(Func):
3263    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
3264
3265
3266class WeekOfYear(Func):
3267    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
3268
3269
3270class LastDateOfMonth(Func):
3271    pass
3272
3273
3274class Extract(Func):
3275    arg_types = {"this": True, "expression": True}
3276
3277
3278class TimestampAdd(Func, TimeUnit):
3279    arg_types = {"this": True, "expression": True, "unit": False}
3280
3281
3282class TimestampSub(Func, TimeUnit):
3283    arg_types = {"this": True, "expression": True, "unit": False}
3284
3285
3286class TimestampDiff(Func, TimeUnit):
3287    arg_types = {"this": True, "expression": True, "unit": False}
3288
3289
3290class TimestampTrunc(Func, TimeUnit):
3291    arg_types = {"this": True, "unit": True, "zone": False}
3292
3293
3294class TimeAdd(Func, TimeUnit):
3295    arg_types = {"this": True, "expression": True, "unit": False}
3296
3297
3298class TimeSub(Func, TimeUnit):
3299    arg_types = {"this": True, "expression": True, "unit": False}
3300
3301
3302class TimeDiff(Func, TimeUnit):
3303    arg_types = {"this": True, "expression": True, "unit": False}
3304
3305
3306class TimeTrunc(Func, TimeUnit):
3307    arg_types = {"this": True, "unit": True, "zone": False}
3308
3309
3310class DateFromParts(Func):
3311    _sql_names = ["DATEFROMPARTS"]
3312    arg_types = {"year": True, "month": True, "day": True}
3313
3314
3315class DateStrToDate(Func):
3316    pass
3317
3318
3319class DateToDateStr(Func):
3320    pass
3321
3322
3323class DateToDi(Func):
3324    pass
3325
3326
3327class Day(Func):
3328    pass
3329
3330
3331class Decode(Func):
3332    arg_types = {"this": True, "charset": True, "replace": False}
3333
3334
3335class DiToDate(Func):
3336    pass
3337
3338
3339class Encode(Func):
3340    arg_types = {"this": True, "charset": True}
3341
3342
3343class Exp(Func):
3344    pass
3345
3346
3347class Explode(Func):
3348    pass
3349
3350
3351class Floor(Func):
3352    arg_types = {"this": True, "decimals": False}
3353
3354
3355class Greatest(Func):
3356    arg_types = {"this": True, "expressions": False}
3357    is_var_len_args = True
3358
3359
3360class GroupConcat(Func):
3361    arg_types = {"this": True, "separator": False}
3362
3363
3364class Hex(Func):
3365    pass
3366
3367
3368class If(Func):
3369    arg_types = {"this": True, "true": True, "false": False}
3370
3371
3372class IfNull(Func):
3373    arg_types = {"this": True, "expression": False}
3374    _sql_names = ["IFNULL", "NVL"]
3375
3376
3377class Initcap(Func):
3378    pass
3379
3380
3381class JSONBContains(Binary):
3382    _sql_names = ["JSONB_CONTAINS"]
3383
3384
3385class JSONExtract(Binary, Func):
3386    _sql_names = ["JSON_EXTRACT"]
3387
3388
3389class JSONExtractScalar(JSONExtract):
3390    _sql_names = ["JSON_EXTRACT_SCALAR"]
3391
3392
3393class JSONBExtract(JSONExtract):
3394    _sql_names = ["JSONB_EXTRACT"]
3395
3396
3397class JSONBExtractScalar(JSONExtract):
3398    _sql_names = ["JSONB_EXTRACT_SCALAR"]
3399
3400
3401class Least(Func):
3402    arg_types = {"this": True, "expressions": False}
3403    is_var_len_args = True
3404
3405
3406class Length(Func):
3407    pass
3408
3409
3410class Levenshtein(Func):
3411    arg_types = {
3412        "this": True,
3413        "expression": False,
3414        "ins_cost": False,
3415        "del_cost": False,
3416        "sub_cost": False,
3417    }
3418
3419
3420class Ln(Func):
3421    pass
3422
3423
3424class Log(Func):
3425    arg_types = {"this": True, "expression": False}
3426
3427
3428class Log2(Func):
3429    pass
3430
3431
3432class Log10(Func):
3433    pass
3434
3435
3436class LogicalOr(AggFunc):
3437    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
3438
3439
3440class Lower(Func):
3441    _sql_names = ["LOWER", "LCASE"]
3442
3443
3444class Map(Func):
3445    arg_types = {"keys": False, "values": False}
3446
3447
3448class VarMap(Func):
3449    arg_types = {"keys": True, "values": True}
3450    is_var_len_args = True
3451
3452
3453class Matches(Func):
3454    """Oracle/Snowflake decode.
3455    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3456    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3457    """
3458
3459    arg_types = {"this": True, "expressions": True}
3460    is_var_len_args = True
3461
3462
3463class Max(AggFunc):
3464    arg_types = {"this": True, "expression": False}
3465
3466
3467class Min(AggFunc):
3468    arg_types = {"this": True, "expression": False}
3469
3470
3471class Month(Func):
3472    pass
3473
3474
3475class Nvl2(Func):
3476    arg_types = {"this": True, "true": True, "false": False}
3477
3478
3479class Posexplode(Func):
3480    pass
3481
3482
3483class Pow(Binary, Func):
3484    _sql_names = ["POWER", "POW"]
3485
3486
3487class PercentileCont(AggFunc):
3488    pass
3489
3490
3491class PercentileDisc(AggFunc):
3492    pass
3493
3494
3495class Quantile(AggFunc):
3496    arg_types = {"this": True, "quantile": True}
3497
3498
3499# Clickhouse-specific:
3500# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/quantiles/#quantiles
3501class Quantiles(AggFunc):
3502    arg_types = {"parameters": True, "expressions": True}
3503
3504
3505class QuantileIf(AggFunc):
3506    arg_types = {"parameters": True, "expressions": True}
3507
3508
3509class ApproxQuantile(Quantile):
3510    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
3511
3512
3513class ReadCSV(Func):
3514    _sql_names = ["READ_CSV"]
3515    is_var_len_args = True
3516    arg_types = {"this": True, "expressions": False}
3517
3518
3519class Reduce(Func):
3520    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
3521
3522
3523class RegexpExtract(Func):
3524    arg_types = {
3525        "this": True,
3526        "expression": True,
3527        "position": False,
3528        "occurrence": False,
3529        "group": False,
3530    }
3531
3532
3533class RegexpLike(Func):
3534    arg_types = {"this": True, "expression": True, "flag": False}
3535
3536
3537class RegexpILike(Func):
3538    arg_types = {"this": True, "expression": True, "flag": False}
3539
3540
3541class RegexpSplit(Func):
3542    arg_types = {"this": True, "expression": True}
3543
3544
3545class Repeat(Func):
3546    arg_types = {"this": True, "times": True}
3547
3548
3549class Round(Func):
3550    arg_types = {"this": True, "decimals": False}
3551
3552
3553class RowNumber(Func):
3554    arg_types: t.Dict[str, t.Any] = {}
3555
3556
3557class SafeDivide(Func):
3558    arg_types = {"this": True, "expression": True}
3559
3560
3561class SetAgg(AggFunc):
3562    pass
3563
3564
3565class SortArray(Func):
3566    arg_types = {"this": True, "asc": False}
3567
3568
3569class Split(Func):
3570    arg_types = {"this": True, "expression": True, "limit": False}
3571
3572
3573# Start may be omitted in the case of postgres
3574# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6
3575class Substring(Func):
3576    arg_types = {"this": True, "start": False, "length": False}
3577
3578
3579class StrPosition(Func):
3580    arg_types = {
3581        "this": True,
3582        "substr": True,
3583        "position": False,
3584        "instance": False,
3585    }
3586
3587
3588class StrToDate(Func):
3589    arg_types = {"this": True, "format": True}
3590
3591
3592class StrToTime(Func):
3593    arg_types = {"this": True, "format": True}
3594
3595
3596# Spark allows unix_timestamp()
3597# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html
3598class StrToUnix(Func):
3599    arg_types = {"this": False, "format": False}
3600
3601
3602class NumberToStr(Func):
3603    arg_types = {"this": True, "format": True}
3604
3605
3606class Struct(Func):
3607    arg_types = {"expressions": True}
3608    is_var_len_args = True
3609
3610
3611class StructExtract(Func):
3612    arg_types = {"this": True, "expression": True}
3613
3614
3615class Sum(AggFunc):
3616    pass
3617
3618
3619class Sqrt(Func):
3620    pass
3621
3622
3623class Stddev(AggFunc):
3624    pass
3625
3626
3627class StddevPop(AggFunc):
3628    pass
3629
3630
3631class StddevSamp(AggFunc):
3632    pass
3633
3634
3635class TimeToStr(Func):
3636    arg_types = {"this": True, "format": True}
3637
3638
3639class TimeToTimeStr(Func):
3640    pass
3641
3642
3643class TimeToUnix(Func):
3644    pass
3645
3646
3647class TimeStrToDate(Func):
3648    pass
3649
3650
3651class TimeStrToTime(Func):
3652    pass
3653
3654
3655class TimeStrToUnix(Func):
3656    pass
3657
3658
3659class Trim(Func):
3660    arg_types = {
3661        "this": True,
3662        "expression": False,
3663        "position": False,
3664        "collation": False,
3665    }
3666
3667
3668class TsOrDsAdd(Func, TimeUnit):
3669    arg_types = {"this": True, "expression": True, "unit": False}
3670
3671
3672class TsOrDsToDateStr(Func):
3673    pass
3674
3675
3676class TsOrDsToDate(Func):
3677    arg_types = {"this": True, "format": False}
3678
3679
3680class TsOrDiToDi(Func):
3681    pass
3682
3683
3684class Unhex(Func):
3685    pass
3686
3687
3688class UnixToStr(Func):
3689    arg_types = {"this": True, "format": False}
3690
3691
3692# https://prestodb.io/docs/current/functions/datetime.html
3693# presto has weird zone/hours/minutes
3694class UnixToTime(Func):
3695    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3696
3697    SECONDS = Literal.string("seconds")
3698    MILLIS = Literal.string("millis")
3699    MICROS = Literal.string("micros")
3700
3701
3702class UnixToTimeStr(Func):
3703    pass
3704
3705
3706class Upper(Func):
3707    _sql_names = ["UPPER", "UCASE"]
3708
3709
3710class Variance(AggFunc):
3711    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
3712
3713
3714class VariancePop(AggFunc):
3715    _sql_names = ["VARIANCE_POP", "VAR_POP"]
3716
3717
3718class Week(Func):
3719    arg_types = {"this": True, "mode": False}
3720
3721
3722class XMLTable(Func):
3723    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
3724
3725
3726class Year(Func):
3727    pass
3728
3729
3730class Use(Expression):
3731    arg_types = {"this": True, "kind": False}
3732
3733
3734class Merge(Expression):
3735    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
3736
3737
3738class When(Func):
3739    arg_types = {"this": True, "then": True}
3740
3741
3742def _norm_args(expression):
3743    args = {}
3744
3745    for k, arg in expression.args.items():
3746        if isinstance(arg, list):
3747            arg = [_norm_arg(a) for a in arg]
3748            if not arg:
3749                arg = None
3750        else:
3751            arg = _norm_arg(arg)
3752
3753        if arg is not None and arg is not False:
3754            args[k] = arg
3755
3756    return args
3757
3758
3759def _norm_arg(arg):
3760    return arg.lower() if isinstance(arg, str) else arg
3761
3762
3763ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func))
3764
3765
3766# Helpers
3767def maybe_parse(
3768    sql_or_expression: str | Expression,
3769    *,
3770    into: t.Optional[IntoType] = None,
3771    dialect: DialectType = None,
3772    prefix: t.Optional[str] = None,
3773    copy: bool = False,
3774    **opts,
3775) -> Expression:
3776    """Gracefully handle a possible string or expression.
3777
3778    Example:
3779        >>> maybe_parse("1")
3780        (LITERAL this: 1, is_string: False)
3781        >>> maybe_parse(to_identifier("x"))
3782        (IDENTIFIER this: x, quoted: False)
3783
3784    Args:
3785        sql_or_expression: the SQL code string or an expression
3786        into: the SQLGlot Expression to parse into
3787        dialect: the dialect used to parse the input expressions (in the case that an
3788            input expression is a SQL string).
3789        prefix: a string to prefix the sql with before it gets parsed
3790            (automatically includes a space)
3791        copy: whether or not to copy the expression.
3792        **opts: other options to use to parse the input expressions (again, in the case
3793            that an input expression is a SQL string).
3794
3795    Returns:
3796        Expression: the parsed or given expression.
3797    """
3798    if isinstance(sql_or_expression, Expression):
3799        if copy:
3800            return sql_or_expression.copy()
3801        return sql_or_expression
3802
3803    import sqlglot
3804
3805    sql = str(sql_or_expression)
3806    if prefix:
3807        sql = f"{prefix} {sql}"
3808    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
3809
3810
3811def _maybe_copy(instance, copy=True):
3812    return instance.copy() if copy else instance
3813
3814
3815def _is_wrong_expression(expression, into):
3816    return isinstance(expression, Expression) and not isinstance(expression, into)
3817
3818
3819def _apply_builder(
3820    expression,
3821    instance,
3822    arg,
3823    copy=True,
3824    prefix=None,
3825    into=None,
3826    dialect=None,
3827    **opts,
3828):
3829    if _is_wrong_expression(expression, into):
3830        expression = into(this=expression)
3831    instance = _maybe_copy(instance, copy)
3832    expression = maybe_parse(
3833        sql_or_expression=expression,
3834        prefix=prefix,
3835        into=into,
3836        dialect=dialect,
3837        **opts,
3838    )
3839    instance.set(arg, expression)
3840    return instance
3841
3842
3843def _apply_child_list_builder(
3844    *expressions,
3845    instance,
3846    arg,
3847    append=True,
3848    copy=True,
3849    prefix=None,
3850    into=None,
3851    dialect=None,
3852    properties=None,
3853    **opts,
3854):
3855    instance = _maybe_copy(instance, copy)
3856    parsed = []
3857    for expression in expressions:
3858        if _is_wrong_expression(expression, into):
3859            expression = into(expressions=[expression])
3860        expression = maybe_parse(
3861            expression,
3862            into=into,
3863            dialect=dialect,
3864            prefix=prefix,
3865            **opts,
3866        )
3867        parsed.extend(expression.expressions)
3868
3869    existing = instance.args.get(arg)
3870    if append and existing:
3871        parsed = existing.expressions + parsed
3872
3873    child = into(expressions=parsed)
3874    for k, v in (properties or {}).items():
3875        child.set(k, v)
3876    instance.set(arg, child)
3877    return instance
3878
3879
3880def _apply_list_builder(
3881    *expressions,
3882    instance,
3883    arg,
3884    append=True,
3885    copy=True,
3886    prefix=None,
3887    into=None,
3888    dialect=None,
3889    **opts,
3890):
3891    inst = _maybe_copy(instance, copy)
3892
3893    expressions = [
3894        maybe_parse(
3895            sql_or_expression=expression,
3896            into=into,
3897            prefix=prefix,
3898            dialect=dialect,
3899            **opts,
3900        )
3901        for expression in expressions
3902    ]
3903
3904    existing_expressions = inst.args.get(arg)
3905    if append and existing_expressions:
3906        expressions = existing_expressions + expressions
3907
3908    inst.set(arg, expressions)
3909    return inst
3910
3911
3912def _apply_conjunction_builder(
3913    *expressions,
3914    instance,
3915    arg,
3916    into=None,
3917    append=True,
3918    copy=True,
3919    dialect=None,
3920    **opts,
3921):
3922    expressions = [exp for exp in expressions if exp is not None and exp != ""]
3923    if not expressions:
3924        return instance
3925
3926    inst = _maybe_copy(instance, copy)
3927
3928    existing = inst.args.get(arg)
3929    if append and existing is not None:
3930        expressions = [existing.this if into else existing] + list(expressions)
3931
3932    node = and_(*expressions, dialect=dialect, **opts)
3933
3934    inst.set(arg, into(this=node) if into else node)
3935    return inst
3936
3937
3938def _combine(expressions, operator, dialect=None, **opts):
3939    expressions = [condition(expression, dialect=dialect, **opts) for expression in expressions]
3940    this = expressions[0]
3941    if expressions[1:]:
3942        this = _wrap_operator(this)
3943    for expression in expressions[1:]:
3944        this = operator(this=this, expression=_wrap_operator(expression))
3945    return this
3946
3947
3948def _wrap_operator(expression):
3949    if isinstance(expression, (And, Or, Not)):
3950        expression = Paren(this=expression)
3951    return expression
3952
3953
3954def union(left, right, distinct=True, dialect=None, **opts):
3955    """
3956    Initializes a syntax tree from one UNION expression.
3957
3958    Example:
3959        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3960        'SELECT * FROM foo UNION SELECT * FROM bla'
3961
3962    Args:
3963        left (str | Expression): the SQL code string corresponding to the left-hand side.
3964            If an `Expression` instance is passed, it will be used as-is.
3965        right (str | Expression): the SQL code string corresponding to the right-hand side.
3966            If an `Expression` instance is passed, it will be used as-is.
3967        distinct (bool): set the DISTINCT flag if and only if this is true.
3968        dialect (str): the dialect used to parse the input expression.
3969        opts (kwargs): other options to use to parse the input expressions.
3970    Returns:
3971        Union: the syntax tree for the UNION expression.
3972    """
3973    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3974    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3975
3976    return Union(this=left, expression=right, distinct=distinct)
3977
3978
3979def intersect(left, right, distinct=True, dialect=None, **opts):
3980    """
3981    Initializes a syntax tree from one INTERSECT expression.
3982
3983    Example:
3984        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
3985        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
3986
3987    Args:
3988        left (str | Expression): the SQL code string corresponding to the left-hand side.
3989            If an `Expression` instance is passed, it will be used as-is.
3990        right (str | Expression): the SQL code string corresponding to the right-hand side.
3991            If an `Expression` instance is passed, it will be used as-is.
3992        distinct (bool): set the DISTINCT flag if and only if this is true.
3993        dialect (str): the dialect used to parse the input expression.
3994        opts (kwargs): other options to use to parse the input expressions.
3995    Returns:
3996        Intersect: the syntax tree for the INTERSECT expression.
3997    """
3998    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3999    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4000
4001    return Intersect(this=left, expression=right, distinct=distinct)
4002
4003
4004def except_(left, right, distinct=True, dialect=None, **opts):
4005    """
4006    Initializes a syntax tree from one EXCEPT expression.
4007
4008    Example:
4009        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
4010        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
4011
4012    Args:
4013        left (str | Expression): the SQL code string corresponding to the left-hand side.
4014            If an `Expression` instance is passed, it will be used as-is.
4015        right (str | Expression): the SQL code string corresponding to the right-hand side.
4016            If an `Expression` instance is passed, it will be used as-is.
4017        distinct (bool): set the DISTINCT flag if and only if this is true.
4018        dialect (str): the dialect used to parse the input expression.
4019        opts (kwargs): other options to use to parse the input expressions.
4020    Returns:
4021        Except: the syntax tree for the EXCEPT statement.
4022    """
4023    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4024    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4025
4026    return Except(this=left, expression=right, distinct=distinct)
4027
4028
4029def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
4030    """
4031    Initializes a syntax tree from one or multiple SELECT expressions.
4032
4033    Example:
4034        >>> select("col1", "col2").from_("tbl").sql()
4035        'SELECT col1, col2 FROM tbl'
4036
4037    Args:
4038        *expressions: the SQL code string to parse as the expressions of a
4039            SELECT statement. If an Expression instance is passed, this is used as-is.
4040        dialect: the dialect used to parse the input expressions (in the case that an
4041            input expression is a SQL string).
4042        **opts: other options to use to parse the input expressions (again, in the case
4043            that an input expression is a SQL string).
4044
4045    Returns:
4046        Select: the syntax tree for the SELECT statement.
4047    """
4048    return Select().select(*expressions, dialect=dialect, **opts)
4049
4050
4051def from_(*expressions, dialect=None, **opts) -> Select:
4052    """
4053    Initializes a syntax tree from a FROM expression.
4054
4055    Example:
4056        >>> from_("tbl").select("col1", "col2").sql()
4057        'SELECT col1, col2 FROM tbl'
4058
4059    Args:
4060        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4061            SELECT statement. If an Expression instance is passed, this is used as-is.
4062        dialect (str): the dialect used to parse the input expression (in the case that the
4063            input expression is a SQL string).
4064        **opts: other options to use to parse the input expressions (again, in the case
4065            that the input expression is a SQL string).
4066
4067    Returns:
4068        Select: the syntax tree for the SELECT statement.
4069    """
4070    return Select().from_(*expressions, dialect=dialect, **opts)
4071
4072
4073def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4074    """
4075    Creates an update statement.
4076
4077    Example:
4078        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4079        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4080
4081    Args:
4082        *properties (Dict[str, Any]): dictionary of properties to set which are
4083            auto converted to sql objects eg None -> NULL
4084        where (str): sql conditional parsed into a WHERE statement
4085        from_ (str): sql statement parsed into a FROM statement
4086        dialect (str): the dialect used to parse the input expressions.
4087        **opts: other options to use to parse the input expressions.
4088
4089    Returns:
4090        Update: the syntax tree for the UPDATE statement.
4091    """
4092    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4093    update.set(
4094        "expressions",
4095        [
4096            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4097            for k, v in properties.items()
4098        ],
4099    )
4100    if from_:
4101        update.set(
4102            "from",
4103            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4104        )
4105    if isinstance(where, Condition):
4106        where = Where(this=where)
4107    if where:
4108        update.set(
4109            "where",
4110            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4111        )
4112    return update
4113
4114
4115def delete(table, where=None, dialect=None, **opts) -> Delete:
4116    """
4117    Builds a delete statement.
4118
4119    Example:
4120        >>> delete("my_table", where="id > 1").sql()
4121        'DELETE FROM my_table WHERE id > 1'
4122
4123    Args:
4124        where (str|Condition): sql conditional parsed into a WHERE statement
4125        dialect (str): the dialect used to parse the input expressions.
4126        **opts: other options to use to parse the input expressions.
4127
4128    Returns:
4129        Delete: the syntax tree for the DELETE statement.
4130    """
4131    return Delete(
4132        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4133        where=Where(this=where)
4134        if isinstance(where, Condition)
4135        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4136    )
4137
4138
4139def condition(expression, dialect=None, **opts) -> Condition:
4140    """
4141    Initialize a logical condition expression.
4142
4143    Example:
4144        >>> condition("x=1").sql()
4145        'x = 1'
4146
4147        This is helpful for composing larger logical syntax trees:
4148        >>> where = condition("x=1")
4149        >>> where = where.and_("y=1")
4150        >>> Select().from_("tbl").select("*").where(where).sql()
4151        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4152
4153    Args:
4154        *expression (str | Expression): the SQL code string to parse.
4155            If an Expression instance is passed, this is used as-is.
4156        dialect (str): the dialect used to parse the input expression (in the case that the
4157            input expression is a SQL string).
4158        **opts: other options to use to parse the input expressions (again, in the case
4159            that the input expression is a SQL string).
4160
4161    Returns:
4162        Condition: the expression
4163    """
4164    return maybe_parse(  # type: ignore
4165        expression,
4166        into=Condition,
4167        dialect=dialect,
4168        **opts,
4169    )
4170
4171
4172def and_(*expressions, dialect=None, **opts) -> And:
4173    """
4174    Combine multiple conditions with an AND logical operator.
4175
4176    Example:
4177        >>> and_("x=1", and_("y=1", "z=1")).sql()
4178        'x = 1 AND (y = 1 AND z = 1)'
4179
4180    Args:
4181        *expressions (str | Expression): the SQL code strings to parse.
4182            If an Expression instance is passed, this is used as-is.
4183        dialect (str): the dialect used to parse the input expression.
4184        **opts: other options to use to parse the input expressions.
4185
4186    Returns:
4187        And: the new condition
4188    """
4189    return _combine(expressions, And, dialect, **opts)
4190
4191
4192def or_(*expressions, dialect=None, **opts) -> Or:
4193    """
4194    Combine multiple conditions with an OR logical operator.
4195
4196    Example:
4197        >>> or_("x=1", or_("y=1", "z=1")).sql()
4198        'x = 1 OR (y = 1 OR z = 1)'
4199
4200    Args:
4201        *expressions (str | Expression): the SQL code strings to parse.
4202            If an Expression instance is passed, this is used as-is.
4203        dialect (str): the dialect used to parse the input expression.
4204        **opts: other options to use to parse the input expressions.
4205
4206    Returns:
4207        Or: the new condition
4208    """
4209    return _combine(expressions, Or, dialect, **opts)
4210
4211
4212def not_(expression, dialect=None, **opts) -> Not:
4213    """
4214    Wrap a condition with a NOT operator.
4215
4216    Example:
4217        >>> not_("this_suit='black'").sql()
4218        "NOT this_suit = 'black'"
4219
4220    Args:
4221        expression (str | Expression): the SQL code strings to parse.
4222            If an Expression instance is passed, this is used as-is.
4223        dialect (str): the dialect used to parse the input expression.
4224        **opts: other options to use to parse the input expressions.
4225
4226    Returns:
4227        Not: the new condition
4228    """
4229    this = condition(
4230        expression,
4231        dialect=dialect,
4232        **opts,
4233    )
4234    return Not(this=_wrap_operator(this))
4235
4236
4237def paren(expression) -> Paren:
4238    return Paren(this=expression)
4239
4240
4241SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$")
4242
4243
4244@t.overload
4245def to_identifier(name: None, quoted: t.Optional[bool] = None) -> None:
4246    ...
4247
4248
4249@t.overload
4250def to_identifier(name: str | Identifier, quoted: t.Optional[bool] = None) -> Identifier:
4251    ...
4252
4253
4254def to_identifier(name, quoted=None):
4255    """Builds an identifier.
4256
4257    Args:
4258        name: The name to turn into an identifier.
4259        quoted: Whether or not force quote the identifier.
4260
4261    Returns:
4262        The identifier ast node.
4263    """
4264
4265    if name is None:
4266        return None
4267
4268    if isinstance(name, Identifier):
4269        identifier = name
4270    elif isinstance(name, str):
4271        identifier = Identifier(
4272            this=name,
4273            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4274        )
4275    else:
4276        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4277    return identifier
4278
4279
4280INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*")
4281
4282
4283def to_interval(interval: str | Literal) -> Interval:
4284    """Builds an interval expression from a string like '1 day' or '5 months'."""
4285    if isinstance(interval, Literal):
4286        if not interval.is_string:
4287            raise ValueError("Invalid interval string.")
4288
4289        interval = interval.this
4290
4291    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4292
4293    if not interval_parts:
4294        raise ValueError("Invalid interval string.")
4295
4296    return Interval(
4297        this=Literal.string(interval_parts.group(1)),
4298        unit=Var(this=interval_parts.group(2)),
4299    )
4300
4301
4302@t.overload
4303def to_table(sql_path: str | Table, **kwargs) -> Table:
4304    ...
4305
4306
4307@t.overload
4308def to_table(sql_path: None, **kwargs) -> None:
4309    ...
4310
4311
4312def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4313    """
4314    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4315    If a table is passed in then that table is returned.
4316
4317    Args:
4318        sql_path: a `[catalog].[schema].[table]` string.
4319
4320    Returns:
4321        A table expression.
4322    """
4323    if sql_path is None or isinstance(sql_path, Table):
4324        return sql_path
4325    if not isinstance(sql_path, str):
4326        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4327
4328    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4329    return Table(this=table_name, db=db, catalog=catalog, **kwargs)
4330
4331
4332def to_column(sql_path: str | Column, **kwargs) -> Column:
4333    """
4334    Create a column from a `[table].[column]` sql path. Schema is optional.
4335
4336    If a column is passed in then that column is returned.
4337
4338    Args:
4339        sql_path: `[table].[column]` string
4340    Returns:
4341        Table: A column expression
4342    """
4343    if sql_path is None or isinstance(sql_path, Column):
4344        return sql_path
4345    if not isinstance(sql_path, str):
4346        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4347    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4348    return Column(this=column_name, table=table_name, **kwargs)
4349
4350
4351def alias_(
4352    expression: str | Expression,
4353    alias: str | Identifier,
4354    table: bool | t.Sequence[str | Identifier] = False,
4355    quoted: t.Optional[bool] = None,
4356    dialect: DialectType = None,
4357    **opts,
4358):
4359    """Create an Alias expression.
4360
4361    Example:
4362        >>> alias_('foo', 'bar').sql()
4363        'foo AS bar'
4364
4365        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4366        '(SELECT 1, 2) AS bar(a, b)'
4367
4368    Args:
4369        expression: the SQL code strings to parse.
4370            If an Expression instance is passed, this is used as-is.
4371        alias: the alias name to use. If the name has
4372            special characters it is quoted.
4373        table: Whether or not to create a table alias, can also be a list of columns.
4374        quoted: whether or not to quote the alias
4375        dialect: the dialect used to parse the input expression.
4376        **opts: other options to use to parse the input expressions.
4377
4378    Returns:
4379        Alias: the aliased expression
4380    """
4381    exp = maybe_parse(expression, dialect=dialect, **opts)
4382    alias = to_identifier(alias, quoted=quoted)
4383
4384    if table:
4385        table_alias = TableAlias(this=alias)
4386        exp.set("alias", table_alias)
4387
4388        if not isinstance(table, bool):
4389            for column in table:
4390                table_alias.append("columns", to_identifier(column, quoted=quoted))
4391
4392        return exp
4393
4394    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4395    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4396    # for the complete Window expression.
4397    #
4398    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4399
4400    if "alias" in exp.arg_types and not isinstance(exp, Window):
4401        exp = exp.copy()
4402        exp.set("alias", alias)
4403        return exp
4404    return Alias(this=exp, alias=alias)
4405
4406
4407def subquery(expression, alias=None, dialect=None, **opts):
4408    """
4409    Build a subquery expression.
4410
4411    Example:
4412        >>> subquery('select x from tbl', 'bar').select('x').sql()
4413        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4414
4415    Args:
4416        expression (str | Expression): the SQL code strings to parse.
4417            If an Expression instance is passed, this is used as-is.
4418        alias (str | Expression): the alias name to use.
4419        dialect (str): the dialect used to parse the input expression.
4420        **opts: other options to use to parse the input expressions.
4421
4422    Returns:
4423        Select: a new select with the subquery expression included
4424    """
4425
4426    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4427    return Select().from_(expression, dialect=dialect, **opts)
4428
4429
4430def column(
4431    col: str | Identifier,
4432    table: t.Optional[str | Identifier] = None,
4433    schema: t.Optional[str | Identifier] = None,
4434    quoted: t.Optional[bool] = None,
4435) -> Column:
4436    """
4437    Build a Column.
4438
4439    Args:
4440        col: column name
4441        table: table name
4442        schema: schema name
4443        quoted: whether or not to force quote each part
4444    Returns:
4445        Column: column instance
4446    """
4447    return Column(
4448        this=to_identifier(col, quoted=quoted),
4449        table=to_identifier(table, quoted=quoted),
4450        schema=to_identifier(schema, quoted=quoted),
4451    )
4452
4453
4454def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4455    """Cast an expression to a data type.
4456
4457    Example:
4458        >>> cast('x + 1', 'int').sql()
4459        'CAST(x + 1 AS INT)'
4460
4461    Args:
4462        expression: The expression to cast.
4463        to: The datatype to cast to.
4464
4465    Returns:
4466        A cast node.
4467    """
4468    expression = maybe_parse(expression, **opts)
4469    return Cast(this=expression, to=DataType.build(to, **opts))
4470
4471
4472def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4473    """Build a Table.
4474
4475    Args:
4476        table (str | Expression): column name
4477        db (str | Expression): db name
4478        catalog (str | Expression): catalog name
4479
4480    Returns:
4481        Table: table instance
4482    """
4483    return Table(
4484        this=to_identifier(table, quoted=quoted),
4485        db=to_identifier(db, quoted=quoted),
4486        catalog=to_identifier(catalog, quoted=quoted),
4487        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4488    )
4489
4490
4491def values(
4492    values: t.Iterable[t.Tuple[t.Any, ...]],
4493    alias: t.Optional[str] = None,
4494    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4495) -> Values:
4496    """Build VALUES statement.
4497
4498    Example:
4499        >>> values([(1, '2')]).sql()
4500        "VALUES (1, '2')"
4501
4502    Args:
4503        values: values statements that will be converted to SQL
4504        alias: optional alias
4505        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4506         If either are provided then an alias is also required.
4507         If a dictionary is provided then the first column of the values will be casted to the expected type
4508         in order to help with type inference.
4509
4510    Returns:
4511        Values: the Values expression object
4512    """
4513    if columns and not alias:
4514        raise ValueError("Alias is required when providing columns")
4515    table_alias = (
4516        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4517        if columns
4518        else TableAlias(this=to_identifier(alias) if alias else None)
4519    )
4520    expressions = [convert(tup) for tup in values]
4521    if columns and isinstance(columns, dict):
4522        types = list(columns.values())
4523        expressions[0].set(
4524            "expressions",
4525            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4526        )
4527    return Values(
4528        expressions=expressions,
4529        alias=table_alias,
4530    )
4531
4532
4533def var(name: t.Optional[str | Expression]) -> Var:
4534    """Build a SQL variable.
4535
4536    Example:
4537        >>> repr(var('x'))
4538        '(VAR this: x)'
4539
4540        >>> repr(var(column('x', table='y')))
4541        '(VAR this: x)'
4542
4543    Args:
4544        name: The name of the var or an expression who's name will become the var.
4545
4546    Returns:
4547        The new variable node.
4548    """
4549    if not name:
4550        raise ValueError(f"Cannot convert empty name into var.")
4551
4552    if isinstance(name, Expression):
4553        name = name.name
4554    return Var(this=name)
4555
4556
4557def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4558    """Build ALTER TABLE... RENAME... expression
4559
4560    Args:
4561        old_name: The old name of the table
4562        new_name: The new name of the table
4563
4564    Returns:
4565        Alter table expression
4566    """
4567    old_table = to_table(old_name)
4568    new_table = to_table(new_name)
4569    return AlterTable(
4570        this=old_table,
4571        actions=[
4572            RenameTable(this=new_table),
4573        ],
4574    )
4575
4576
4577def convert(value) -> Expression:
4578    """Convert a python value into an expression object.
4579
4580    Raises an error if a conversion is not possible.
4581
4582    Args:
4583        value (Any): a python object
4584
4585    Returns:
4586        Expression: the equivalent expression object
4587    """
4588    if isinstance(value, Expression):
4589        return value
4590    if value is None:
4591        return NULL
4592    if isinstance(value, bool):
4593        return Boolean(this=value)
4594    if isinstance(value, str):
4595        return Literal.string(value)
4596    if isinstance(value, float) and math.isnan(value):
4597        return NULL
4598    if isinstance(value, numbers.Number):
4599        return Literal.number(value)
4600    if isinstance(value, tuple):
4601        return Tuple(expressions=[convert(v) for v in value])
4602    if isinstance(value, list):
4603        return Array(expressions=[convert(v) for v in value])
4604    if isinstance(value, dict):
4605        return Map(
4606            keys=[convert(k) for k in value],
4607            values=[convert(v) for v in value.values()],
4608        )
4609    if isinstance(value, datetime.datetime):
4610        datetime_literal = Literal.string(
4611            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4612        )
4613        return TimeStrToTime(this=datetime_literal)
4614    if isinstance(value, datetime.date):
4615        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4616        return DateStrToDate(this=date_literal)
4617    raise ValueError(f"Cannot convert {value}")
4618
4619
4620def replace_children(expression, fun):
4621    """
4622    Replace children of an expression with the result of a lambda fun(child) -> exp.
4623    """
4624    for k, v in expression.args.items():
4625        is_list_arg = isinstance(v, list)
4626
4627        child_nodes = v if is_list_arg else [v]
4628        new_child_nodes = []
4629
4630        for cn in child_nodes:
4631            if isinstance(cn, Expression):
4632                for child_node in ensure_collection(fun(cn)):
4633                    new_child_nodes.append(child_node)
4634                    child_node.parent = expression
4635                    child_node.arg_key = k
4636            else:
4637                new_child_nodes.append(cn)
4638
4639        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
4640
4641
4642def column_table_names(expression):
4643    """
4644    Return all table names referenced through columns in an expression.
4645
4646    Example:
4647        >>> import sqlglot
4648        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4649        ['c', 'a']
4650
4651    Args:
4652        expression (sqlglot.Expression): expression to find table names
4653
4654    Returns:
4655        list: A list of unique names
4656    """
4657    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
4658
4659
4660def table_name(table) -> str:
4661    """Get the full name of a table as a string.
4662
4663    Args:
4664        table (exp.Table | str): table expression node or string.
4665
4666    Examples:
4667        >>> from sqlglot import exp, parse_one
4668        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4669        'a.b.c'
4670
4671    Returns:
4672        The table name.
4673    """
4674
4675    table = maybe_parse(table, into=Table)
4676
4677    if not table:
4678        raise ValueError(f"Cannot parse {table}")
4679
4680    return ".".join(
4681        part
4682        for part in (
4683            table.text("catalog"),
4684            table.text("db"),
4685            table.name,
4686        )
4687        if part
4688    )
4689
4690
4691def replace_tables(expression, mapping):
4692    """Replace all tables in expression according to the mapping.
4693
4694    Args:
4695        expression (sqlglot.Expression): expression node to be transformed and replaced.
4696        mapping (Dict[str, str]): mapping of table names.
4697
4698    Examples:
4699        >>> from sqlglot import exp, parse_one
4700        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4701        'SELECT * FROM c'
4702
4703    Returns:
4704        The mapped expression.
4705    """
4706
4707    def _replace_tables(node):
4708        if isinstance(node, Table):
4709            new_name = mapping.get(table_name(node))
4710            if new_name:
4711                return to_table(
4712                    new_name,
4713                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4714                )
4715        return node
4716
4717    return expression.transform(_replace_tables)
4718
4719
4720def replace_placeholders(expression, *args, **kwargs):
4721    """Replace placeholders in an expression.
4722
4723    Args:
4724        expression (sqlglot.Expression): expression node to be transformed and replaced.
4725        args: positional names that will substitute unnamed placeholders in the given order.
4726        kwargs: keyword arguments that will substitute named placeholders.
4727
4728    Examples:
4729        >>> from sqlglot import exp, parse_one
4730        >>> replace_placeholders(
4731        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4732        ... ).sql()
4733        'SELECT * FROM foo WHERE a = b'
4734
4735    Returns:
4736        The mapped expression.
4737    """
4738
4739    def _replace_placeholders(node, args, **kwargs):
4740        if isinstance(node, Placeholder):
4741            if node.name:
4742                new_name = kwargs.get(node.name)
4743                if new_name:
4744                    return to_identifier(new_name)
4745            else:
4746                try:
4747                    return to_identifier(next(args))
4748                except StopIteration:
4749                    pass
4750        return node
4751
4752    return expression.transform(_replace_placeholders, iter(args), **kwargs)
4753
4754
4755def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4756    """Transforms an expression by expanding all referenced sources into subqueries.
4757
4758    Examples:
4759        >>> from sqlglot import parse_one
4760        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4761        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4762
4763    Args:
4764        expression: The expression to expand.
4765        sources: A dictionary of name to Subqueryables.
4766        copy: Whether or not to copy the expression during transformation. Defaults to True.
4767
4768    Returns:
4769        The transformed expression.
4770    """
4771
4772    def _expand(node: Expression):
4773        if isinstance(node, Table):
4774            name = table_name(node)
4775            source = sources.get(name)
4776            if source:
4777                subquery = source.subquery(node.alias or name)
4778                subquery.comments = [f"source: {name}"]
4779                return subquery
4780        return node
4781
4782    return expression.transform(_expand, copy=copy)
4783
4784
4785def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4786    """
4787    Returns a Func expression.
4788
4789    Examples:
4790        >>> func("abs", 5).sql()
4791        'ABS(5)'
4792
4793        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4794        'CAST(5 AS DOUBLE)'
4795
4796    Args:
4797        name: the name of the function to build.
4798        args: the args used to instantiate the function of interest.
4799        dialect: the source dialect.
4800        kwargs: the kwargs used to instantiate the function of interest.
4801
4802    Note:
4803        The arguments `args` and `kwargs` are mutually exclusive.
4804
4805    Returns:
4806        An instance of the function of interest, or an anonymous function, if `name` doesn't
4807        correspond to an existing `sqlglot.expressions.Func` class.
4808    """
4809    if args and kwargs:
4810        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4811
4812    from sqlglot.dialects.dialect import Dialect
4813
4814    args = tuple(convert(arg) for arg in args)
4815    kwargs = {key: convert(value) for key, value in kwargs.items()}
4816
4817    parser = Dialect.get_or_raise(dialect)().parser()
4818    from_args_list = parser.FUNCTIONS.get(name.upper())
4819
4820    if from_args_list:
4821        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4822    else:
4823        kwargs = kwargs or {"expressions": args}
4824        function = Anonymous(this=name, **kwargs)
4825
4826    for error_message in function.error_messages(args):
4827        raise ValueError(error_message)
4828
4829    return function
4830
4831
4832def true():
4833    """
4834    Returns a true Boolean expression.
4835    """
4836    return Boolean(this=True)
4837
4838
4839def false():
4840    """
4841    Returns a false Boolean expression.
4842    """
4843    return Boolean(this=False)
4844
4845
4846def null():
4847    """
4848    Returns a Null expression.
4849    """
4850    return Null()
4851
4852
4853# TODO: deprecate this
4854TRUE = Boolean(this=True)
4855FALSE = Boolean(this=False)
4856NULL = Null()
class Expression:
 54class Expression(metaclass=_Expression):
 55    """
 56    The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary
 57    context, such as its child expressions, their names (arg keys), and whether a given child expression
 58    is optional or not.
 59
 60    Attributes:
 61        key: a unique key for each class in the Expression hierarchy. This is useful for hashing
 62            and representing expressions as strings.
 63        arg_types: determines what arguments (child nodes) are supported by an expression. It
 64            maps arg keys to booleans that indicate whether the corresponding args are optional.
 65
 66    Example:
 67        >>> class Foo(Expression):
 68        ...     arg_types = {"this": True, "expression": False}
 69
 70        The above definition informs us that Foo is an Expression that requires an argument called
 71        "this" and may also optionally receive an argument called "expression".
 72
 73    Args:
 74        args: a mapping used for retrieving the arguments of an expression, given their arg keys.
 75        parent: a reference to the parent expression (or None, in case of root expressions).
 76        arg_key: the arg key an expression is associated with, i.e. the name its parent expression
 77            uses to refer to it.
 78        comments: a list of comments that are associated with a given expression. This is used in
 79            order to preserve comments when transpiling SQL code.
 80        _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the
 81            optimizer, in order to enable some transformations that require type information.
 82    """
 83
 84    key = "expression"
 85    arg_types = {"this": True}
 86    __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta")
 87
 88    def __init__(self, **args: t.Any):
 89        self.args: t.Dict[str, t.Any] = args
 90        self.parent: t.Optional[Expression] = None
 91        self.arg_key: t.Optional[str] = None
 92        self.comments: t.Optional[t.List[str]] = None
 93        self._type: t.Optional[DataType] = None
 94        self._meta: t.Optional[t.Dict[str, t.Any]] = None
 95
 96        for arg_key, value in self.args.items():
 97            self._set_parent(arg_key, value)
 98
 99    def __eq__(self, other) -> bool:
100        return type(self) is type(other) and _norm_args(self) == _norm_args(other)
101
102    def __hash__(self) -> int:
103        return hash(
104            (
105                self.key,
106                tuple(
107                    (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items()
108                ),
109            )
110        )
111
112    @property
113    def this(self):
114        """
115        Retrieves the argument with key "this".
116        """
117        return self.args.get("this")
118
119    @property
120    def expression(self):
121        """
122        Retrieves the argument with key "expression".
123        """
124        return self.args.get("expression")
125
126    @property
127    def expressions(self):
128        """
129        Retrieves the argument with key "expressions".
130        """
131        return self.args.get("expressions") or []
132
133    def text(self, key) -> str:
134        """
135        Returns a textual representation of the argument corresponding to "key". This can only be used
136        for args that are strings or leaf Expression instances, such as identifiers and literals.
137        """
138        field = self.args.get(key)
139        if isinstance(field, str):
140            return field
141        if isinstance(field, (Identifier, Literal, Var)):
142            return field.this
143        if isinstance(field, (Star, Null)):
144            return field.name
145        return ""
146
147    @property
148    def is_string(self) -> bool:
149        """
150        Checks whether a Literal expression is a string.
151        """
152        return isinstance(self, Literal) and self.args["is_string"]
153
154    @property
155    def is_number(self) -> bool:
156        """
157        Checks whether a Literal expression is a number.
158        """
159        return isinstance(self, Literal) and not self.args["is_string"]
160
161    @property
162    def is_int(self) -> bool:
163        """
164        Checks whether a Literal expression is an integer.
165        """
166        if self.is_number:
167            try:
168                int(self.name)
169                return True
170            except ValueError:
171                pass
172        return False
173
174    @property
175    def is_star(self) -> bool:
176        """Checks whether an expression is a star."""
177        return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star))
178
179    @property
180    def alias(self) -> str:
181        """
182        Returns the alias of the expression, or an empty string if it's not aliased.
183        """
184        if isinstance(self.args.get("alias"), TableAlias):
185            return self.args["alias"].name
186        return self.text("alias")
187
188    @property
189    def name(self) -> str:
190        return self.text("this")
191
192    @property
193    def alias_or_name(self):
194        return self.alias or self.name
195
196    @property
197    def output_name(self):
198        """
199        Name of the output column if this expression is a selection.
200
201        If the Expression has no output name, an empty string is returned.
202
203        Example:
204            >>> from sqlglot import parse_one
205            >>> parse_one("SELECT a").expressions[0].output_name
206            'a'
207            >>> parse_one("SELECT b AS c").expressions[0].output_name
208            'c'
209            >>> parse_one("SELECT 1 + 2").expressions[0].output_name
210            ''
211        """
212        return ""
213
214    @property
215    def type(self) -> t.Optional[DataType]:
216        return self._type
217
218    @type.setter
219    def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None:
220        if dtype and not isinstance(dtype, DataType):
221            dtype = DataType.build(dtype)
222        self._type = dtype  # type: ignore
223
224    @property
225    def meta(self) -> t.Dict[str, t.Any]:
226        if self._meta is None:
227            self._meta = {}
228        return self._meta
229
230    def __deepcopy__(self, memo):
231        copy = self.__class__(**deepcopy(self.args))
232        if self.comments is not None:
233            copy.comments = deepcopy(self.comments)
234
235        if self._type is not None:
236            copy._type = self._type.copy()
237
238        if self._meta is not None:
239            copy._meta = deepcopy(self._meta)
240
241        return copy
242
243    def copy(self):
244        """
245        Returns a deep copy of the expression.
246        """
247        new = deepcopy(self)
248        new.parent = self.parent
249        for item, parent, _ in new.bfs():
250            if isinstance(item, Expression) and parent:
251                item.parent = parent
252        return new
253
254    def append(self, arg_key, value):
255        """
256        Appends value to arg_key if it's a list or sets it as a new list.
257
258        Args:
259            arg_key (str): name of the list expression arg
260            value (Any): value to append to the list
261        """
262        if not isinstance(self.args.get(arg_key), list):
263            self.args[arg_key] = []
264        self.args[arg_key].append(value)
265        self._set_parent(arg_key, value)
266
267    def set(self, arg_key, value):
268        """
269        Sets `arg_key` to `value`.
270
271        Args:
272            arg_key (str): name of the expression arg.
273            value: value to set the arg to.
274        """
275        self.args[arg_key] = value
276        self._set_parent(arg_key, value)
277
278    def _set_parent(self, arg_key, value):
279        if isinstance(value, Expression):
280            value.parent = self
281            value.arg_key = arg_key
282        elif isinstance(value, list):
283            for v in value:
284                if isinstance(v, Expression):
285                    v.parent = self
286                    v.arg_key = arg_key
287
288    @property
289    def depth(self):
290        """
291        Returns the depth of this tree.
292        """
293        if self.parent:
294            return self.parent.depth + 1
295        return 0
296
297    def find(self, *expression_types, bfs=True):
298        """
299        Returns the first node in this tree which matches at least one of
300        the specified types.
301
302        Args:
303            expression_types (type): the expression type(s) to match.
304
305        Returns:
306            The node which matches the criteria or None if no such node was found.
307        """
308        return next(self.find_all(*expression_types, bfs=bfs), None)
309
310    def find_all(self, *expression_types, bfs=True):
311        """
312        Returns a generator object which visits all nodes in this tree and only
313        yields those that match at least one of the specified expression types.
314
315        Args:
316            expression_types (type): the expression type(s) to match.
317
318        Returns:
319            The generator object.
320        """
321        for expression, _, _ in self.walk(bfs=bfs):
322            if isinstance(expression, expression_types):
323                yield expression
324
325    def find_ancestor(self, *expression_types):
326        """
327        Returns a nearest parent matching expression_types.
328
329        Args:
330            expression_types (type): the expression type(s) to match.
331
332        Returns:
333            The parent node.
334        """
335        ancestor = self.parent
336        while ancestor and not isinstance(ancestor, expression_types):
337            ancestor = ancestor.parent
338        return ancestor
339
340    @property
341    def parent_select(self):
342        """
343        Returns the parent select statement.
344        """
345        return self.find_ancestor(Select)
346
347    def root(self) -> Expression:
348        """
349        Returns the root expression of this tree.
350        """
351        expression = self
352        while expression.parent:
353            expression = expression.parent
354        return expression
355
356    def walk(self, bfs=True, prune=None):
357        """
358        Returns a generator object which visits all nodes in this tree.
359
360        Args:
361            bfs (bool): if set to True the BFS traversal order will be applied,
362                otherwise the DFS traversal will be used instead.
363            prune ((node, parent, arg_key) -> bool): callable that returns True if
364                the generator should stop traversing this branch of the tree.
365
366        Returns:
367            the generator object.
368        """
369        if bfs:
370            yield from self.bfs(prune=prune)
371        else:
372            yield from self.dfs(prune=prune)
373
374    def dfs(self, parent=None, key=None, prune=None):
375        """
376        Returns a generator object which visits all nodes in this tree in
377        the DFS (Depth-first) order.
378
379        Returns:
380            The generator object.
381        """
382        parent = parent or self.parent
383        yield self, parent, key
384        if prune and prune(self, parent, key):
385            return
386
387        for k, v in self.args.items():
388            for node in ensure_collection(v):
389                if isinstance(node, Expression):
390                    yield from node.dfs(self, k, prune)
391
392    def bfs(self, prune=None):
393        """
394        Returns a generator object which visits all nodes in this tree in
395        the BFS (Breadth-first) order.
396
397        Returns:
398            The generator object.
399        """
400        queue = deque([(self, self.parent, None)])
401
402        while queue:
403            item, parent, key = queue.popleft()
404
405            yield item, parent, key
406            if prune and prune(item, parent, key):
407                continue
408
409            if isinstance(item, Expression):
410                for k, v in item.args.items():
411                    for node in ensure_collection(v):
412                        if isinstance(node, Expression):
413                            queue.append((node, item, k))
414
415    def unnest(self):
416        """
417        Returns the first non parenthesis child or self.
418        """
419        expression = self
420        while isinstance(expression, Paren):
421            expression = expression.this
422        return expression
423
424    def unalias(self):
425        """
426        Returns the inner expression if this is an Alias.
427        """
428        if isinstance(self, Alias):
429            return self.this
430        return self
431
432    def unnest_operands(self):
433        """
434        Returns unnested operands as a tuple.
435        """
436        return tuple(arg.unnest() for arg in self.args.values() if arg)
437
438    def flatten(self, unnest=True):
439        """
440        Returns a generator which yields child nodes who's parents are the same class.
441
442        A AND B AND C -> [A, B, C]
443        """
444        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
445            if not isinstance(node, self.__class__):
446                yield node.unnest() if unnest else node
447
448    def __str__(self):
449        return self.sql()
450
451    def __repr__(self):
452        return self._to_s()
453
454    def sql(self, dialect: DialectType = None, **opts) -> str:
455        """
456        Returns SQL string representation of this tree.
457
458        Args:
459            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
460            opts: other `sqlglot.generator.Generator` options.
461
462        Returns:
463            The SQL string.
464        """
465        from sqlglot.dialects import Dialect
466
467        return Dialect.get_or_raise(dialect)().generate(self, **opts)
468
469    def _to_s(self, hide_missing: bool = True, level: int = 0) -> str:
470        indent = "" if not level else "\n"
471        indent += "".join(["  "] * level)
472        left = f"({self.key.upper()} "
473
474        args: t.Dict[str, t.Any] = {
475            k: ", ".join(
476                v._to_s(hide_missing=hide_missing, level=level + 1)
477                if hasattr(v, "_to_s")
478                else str(v)
479                for v in ensure_collection(vs)
480                if v is not None
481            )
482            for k, vs in self.args.items()
483        }
484        args["comments"] = self.comments
485        args["type"] = self.type
486        args = {k: v for k, v in args.items() if v or not hide_missing}
487
488        right = ", ".join(f"{k}: {v}" for k, v in args.items())
489        right += ")"
490
491        return indent + left + right
492
493    def transform(self, fun, *args, copy=True, **kwargs):
494        """
495        Recursively visits all tree nodes (excluding already transformed ones)
496        and applies the given transformation function to each node.
497
498        Args:
499            fun (function): a function which takes a node as an argument and returns a
500                new transformed node or the same node without modifications. If the function
501                returns None, then the corresponding node will be removed from the syntax tree.
502            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
503                modified in place.
504
505        Returns:
506            The transformed tree.
507        """
508        node = self.copy() if copy else self
509        new_node = fun(node, *args, **kwargs)
510
511        if new_node is None or not isinstance(new_node, Expression):
512            return new_node
513        if new_node is not node:
514            new_node.parent = node.parent
515            return new_node
516
517        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
518        return new_node
519
520    def replace(self, expression):
521        """
522        Swap out this expression with a new expression.
523
524        For example::
525
526            >>> tree = Select().select("x").from_("tbl")
527            >>> tree.find(Column).replace(Column(this="y"))
528            (COLUMN this: y)
529            >>> tree.sql()
530            'SELECT y FROM tbl'
531
532        Args:
533            expression (Expression|None): new node
534
535        Returns:
536            The new expression or expressions.
537        """
538        if not self.parent:
539            return expression
540
541        parent = self.parent
542        self.parent = None
543
544        replace_children(parent, lambda child: expression if child is self else child)
545        return expression
546
547    def pop(self):
548        """
549        Remove this expression from its AST.
550        """
551        self.replace(None)
552
553    def assert_is(self, type_):
554        """
555        Assert that this `Expression` is an instance of `type_`.
556
557        If it is NOT an instance of `type_`, this raises an assertion error.
558        Otherwise, this returns this expression.
559
560        Examples:
561            This is useful for type security in chained expressions:
562
563            >>> import sqlglot
564            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
565            'SELECT x, z FROM y'
566        """
567        assert isinstance(self, type_)
568        return self
569
570    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
571        """
572        Checks if this expression is valid (e.g. all mandatory args are set).
573
574        Args:
575            args: a sequence of values that were used to instantiate a Func expression. This is used
576                to check that the provided arguments don't exceed the function argument limit.
577
578        Returns:
579            A list of error messages for all possible errors that were found.
580        """
581        errors: t.List[str] = []
582
583        for k in self.args:
584            if k not in self.arg_types:
585                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
586        for k, mandatory in self.arg_types.items():
587            v = self.args.get(k)
588            if mandatory and (v is None or (isinstance(v, list) and not v)):
589                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
590
591        if (
592            args
593            and isinstance(self, Func)
594            and len(args) > len(self.arg_types)
595            and not self.is_var_len_args
596        ):
597            errors.append(
598                f"The number of provided arguments ({len(args)}) is greater than "
599                f"the maximum number of supported arguments ({len(self.arg_types)})"
600            )
601
602        return errors
603
604    def dump(self):
605        """
606        Dump this Expression to a JSON-serializable dict.
607        """
608        from sqlglot.serde import dump
609
610        return dump(self)
611
612    @classmethod
613    def load(cls, obj):
614        """
615        Load a dict (as returned by `Expression.dump`) into an Expression instance.
616        """
617        from sqlglot.serde import load
618
619        return load(obj)

The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.

Attributes:
  • key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
  • arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
Example:
>>> class Foo(Expression):
...     arg_types = {"this": True, "expression": False}

The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".

Arguments:
  • args: a mapping used for retrieving the arguments of an expression, given their arg keys.
  • parent: a reference to the parent expression (or None, in case of root expressions).
  • arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
  • comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
  • _type: the sqlglot.expressions.DataType type of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
Expression(**args: Any)
88    def __init__(self, **args: t.Any):
89        self.args: t.Dict[str, t.Any] = args
90        self.parent: t.Optional[Expression] = None
91        self.arg_key: t.Optional[str] = None
92        self.comments: t.Optional[t.List[str]] = None
93        self._type: t.Optional[DataType] = None
94        self._meta: t.Optional[t.Dict[str, t.Any]] = None
95
96        for arg_key, value in self.args.items():
97            self._set_parent(arg_key, value)
this

Retrieves the argument with key "this".

expression

Retrieves the argument with key "expression".

expressions

Retrieves the argument with key "expressions".

def text(self, key) -> str:
133    def text(self, key) -> str:
134        """
135        Returns a textual representation of the argument corresponding to "key". This can only be used
136        for args that are strings or leaf Expression instances, such as identifiers and literals.
137        """
138        field = self.args.get(key)
139        if isinstance(field, str):
140            return field
141        if isinstance(field, (Identifier, Literal, Var)):
142            return field.this
143        if isinstance(field, (Star, Null)):
144            return field.name
145        return ""

Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.

is_string: bool

Checks whether a Literal expression is a string.

is_number: bool

Checks whether a Literal expression is a number.

is_int: bool

Checks whether a Literal expression is an integer.

is_star: bool

Checks whether an expression is a star.

alias: str

Returns the alias of the expression, or an empty string if it's not aliased.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def copy(self):
243    def copy(self):
244        """
245        Returns a deep copy of the expression.
246        """
247        new = deepcopy(self)
248        new.parent = self.parent
249        for item, parent, _ in new.bfs():
250            if isinstance(item, Expression) and parent:
251                item.parent = parent
252        return new

Returns a deep copy of the expression.

def append(self, arg_key, value):
254    def append(self, arg_key, value):
255        """
256        Appends value to arg_key if it's a list or sets it as a new list.
257
258        Args:
259            arg_key (str): name of the list expression arg
260            value (Any): value to append to the list
261        """
262        if not isinstance(self.args.get(arg_key), list):
263            self.args[arg_key] = []
264        self.args[arg_key].append(value)
265        self._set_parent(arg_key, value)

Appends value to arg_key if it's a list or sets it as a new list.

Arguments:
  • arg_key (str): name of the list expression arg
  • value (Any): value to append to the list
def set(self, arg_key, value):
267    def set(self, arg_key, value):
268        """
269        Sets `arg_key` to `value`.
270
271        Args:
272            arg_key (str): name of the expression arg.
273            value: value to set the arg to.
274        """
275        self.args[arg_key] = value
276        self._set_parent(arg_key, value)

Sets arg_key to value.

Arguments:
  • arg_key (str): name of the expression arg.
  • value: value to set the arg to.
depth

Returns the depth of this tree.

def find(self, *expression_types, bfs=True):
297    def find(self, *expression_types, bfs=True):
298        """
299        Returns the first node in this tree which matches at least one of
300        the specified types.
301
302        Args:
303            expression_types (type): the expression type(s) to match.
304
305        Returns:
306            The node which matches the criteria or None if no such node was found.
307        """
308        return next(self.find_all(*expression_types, bfs=bfs), None)

Returns the first node in this tree which matches at least one of the specified types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The node which matches the criteria or None if no such node was found.

def find_all(self, *expression_types, bfs=True):
310    def find_all(self, *expression_types, bfs=True):
311        """
312        Returns a generator object which visits all nodes in this tree and only
313        yields those that match at least one of the specified expression types.
314
315        Args:
316            expression_types (type): the expression type(s) to match.
317
318        Returns:
319            The generator object.
320        """
321        for expression, _, _ in self.walk(bfs=bfs):
322            if isinstance(expression, expression_types):
323                yield expression

Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The generator object.

def find_ancestor(self, *expression_types):
325    def find_ancestor(self, *expression_types):
326        """
327        Returns a nearest parent matching expression_types.
328
329        Args:
330            expression_types (type): the expression type(s) to match.
331
332        Returns:
333            The parent node.
334        """
335        ancestor = self.parent
336        while ancestor and not isinstance(ancestor, expression_types):
337            ancestor = ancestor.parent
338        return ancestor

Returns a nearest parent matching expression_types.

Arguments:
  • expression_types (type): the expression type(s) to match.
Returns:

The parent node.

parent_select

Returns the parent select statement.

def root(self) -> sqlglot.expressions.Expression:
347    def root(self) -> Expression:
348        """
349        Returns the root expression of this tree.
350        """
351        expression = self
352        while expression.parent:
353            expression = expression.parent
354        return expression

Returns the root expression of this tree.

def walk(self, bfs=True, prune=None):
356    def walk(self, bfs=True, prune=None):
357        """
358        Returns a generator object which visits all nodes in this tree.
359
360        Args:
361            bfs (bool): if set to True the BFS traversal order will be applied,
362                otherwise the DFS traversal will be used instead.
363            prune ((node, parent, arg_key) -> bool): callable that returns True if
364                the generator should stop traversing this branch of the tree.
365
366        Returns:
367            the generator object.
368        """
369        if bfs:
370            yield from self.bfs(prune=prune)
371        else:
372            yield from self.dfs(prune=prune)

Returns a generator object which visits all nodes in this tree.

Arguments:
  • bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
  • prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:

the generator object.

def dfs(self, parent=None, key=None, prune=None):
374    def dfs(self, parent=None, key=None, prune=None):
375        """
376        Returns a generator object which visits all nodes in this tree in
377        the DFS (Depth-first) order.
378
379        Returns:
380            The generator object.
381        """
382        parent = parent or self.parent
383        yield self, parent, key
384        if prune and prune(self, parent, key):
385            return
386
387        for k, v in self.args.items():
388            for node in ensure_collection(v):
389                if isinstance(node, Expression):
390                    yield from node.dfs(self, k, prune)

Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.

Returns:

The generator object.

def bfs(self, prune=None):
392    def bfs(self, prune=None):
393        """
394        Returns a generator object which visits all nodes in this tree in
395        the BFS (Breadth-first) order.
396
397        Returns:
398            The generator object.
399        """
400        queue = deque([(self, self.parent, None)])
401
402        while queue:
403            item, parent, key = queue.popleft()
404
405            yield item, parent, key
406            if prune and prune(item, parent, key):
407                continue
408
409            if isinstance(item, Expression):
410                for k, v in item.args.items():
411                    for node in ensure_collection(v):
412                        if isinstance(node, Expression):
413                            queue.append((node, item, k))

Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.

Returns:

The generator object.

def unnest(self):
415    def unnest(self):
416        """
417        Returns the first non parenthesis child or self.
418        """
419        expression = self
420        while isinstance(expression, Paren):
421            expression = expression.this
422        return expression

Returns the first non parenthesis child or self.

def unalias(self):
424    def unalias(self):
425        """
426        Returns the inner expression if this is an Alias.
427        """
428        if isinstance(self, Alias):
429            return self.this
430        return self

Returns the inner expression if this is an Alias.

def unnest_operands(self):
432    def unnest_operands(self):
433        """
434        Returns unnested operands as a tuple.
435        """
436        return tuple(arg.unnest() for arg in self.args.values() if arg)

Returns unnested operands as a tuple.

def flatten(self, unnest=True):
438    def flatten(self, unnest=True):
439        """
440        Returns a generator which yields child nodes who's parents are the same class.
441
442        A AND B AND C -> [A, B, C]
443        """
444        for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)):
445            if not isinstance(node, self.__class__):
446                yield node.unnest() if unnest else node

Returns a generator which yields child nodes who's parents are the same class.

A AND B AND C -> [A, B, C]

def sql( self, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> str:
454    def sql(self, dialect: DialectType = None, **opts) -> str:
455        """
456        Returns SQL string representation of this tree.
457
458        Args:
459            dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
460            opts: other `sqlglot.generator.Generator` options.
461
462        Returns:
463            The SQL string.
464        """
465        from sqlglot.dialects import Dialect
466
467        return Dialect.get_or_raise(dialect)().generate(self, **opts)

Returns SQL string representation of this tree.

Arguments:
  • dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
  • opts: other sqlglot.generator.Generator options.
Returns:

The SQL string.

def transform(self, fun, *args, copy=True, **kwargs):
493    def transform(self, fun, *args, copy=True, **kwargs):
494        """
495        Recursively visits all tree nodes (excluding already transformed ones)
496        and applies the given transformation function to each node.
497
498        Args:
499            fun (function): a function which takes a node as an argument and returns a
500                new transformed node or the same node without modifications. If the function
501                returns None, then the corresponding node will be removed from the syntax tree.
502            copy (bool): if set to True a new tree instance is constructed, otherwise the tree is
503                modified in place.
504
505        Returns:
506            The transformed tree.
507        """
508        node = self.copy() if copy else self
509        new_node = fun(node, *args, **kwargs)
510
511        if new_node is None or not isinstance(new_node, Expression):
512            return new_node
513        if new_node is not node:
514            new_node.parent = node.parent
515            return new_node
516
517        replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs))
518        return new_node

Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.

Arguments:
  • fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
  • copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:

The transformed tree.

def replace(self, expression):
520    def replace(self, expression):
521        """
522        Swap out this expression with a new expression.
523
524        For example::
525
526            >>> tree = Select().select("x").from_("tbl")
527            >>> tree.find(Column).replace(Column(this="y"))
528            (COLUMN this: y)
529            >>> tree.sql()
530            'SELECT y FROM tbl'
531
532        Args:
533            expression (Expression|None): new node
534
535        Returns:
536            The new expression or expressions.
537        """
538        if not self.parent:
539            return expression
540
541        parent = self.parent
542        self.parent = None
543
544        replace_children(parent, lambda child: expression if child is self else child)
545        return expression

Swap out this expression with a new expression.

For example::

>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
  • expression (Expression|None): new node
Returns:

The new expression or expressions.

def pop(self):
547    def pop(self):
548        """
549        Remove this expression from its AST.
550        """
551        self.replace(None)

Remove this expression from its AST.

def assert_is(self, type_):
553    def assert_is(self, type_):
554        """
555        Assert that this `Expression` is an instance of `type_`.
556
557        If it is NOT an instance of `type_`, this raises an assertion error.
558        Otherwise, this returns this expression.
559
560        Examples:
561            This is useful for type security in chained expressions:
562
563            >>> import sqlglot
564            >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
565            'SELECT x, z FROM y'
566        """
567        assert isinstance(self, type_)
568        return self

Assert that this Expression is an instance of type_.

If it is NOT an instance of type_, this raises an assertion error. Otherwise, this returns this expression.

Examples:

This is useful for type security in chained expressions:

>>> import sqlglot
>>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql()
'SELECT x, z FROM y'
def error_messages(self, args: Optional[Sequence] = None) -> List[str]:
570    def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]:
571        """
572        Checks if this expression is valid (e.g. all mandatory args are set).
573
574        Args:
575            args: a sequence of values that were used to instantiate a Func expression. This is used
576                to check that the provided arguments don't exceed the function argument limit.
577
578        Returns:
579            A list of error messages for all possible errors that were found.
580        """
581        errors: t.List[str] = []
582
583        for k in self.args:
584            if k not in self.arg_types:
585                errors.append(f"Unexpected keyword: '{k}' for {self.__class__}")
586        for k, mandatory in self.arg_types.items():
587            v = self.args.get(k)
588            if mandatory and (v is None or (isinstance(v, list) and not v)):
589                errors.append(f"Required keyword: '{k}' missing for {self.__class__}")
590
591        if (
592            args
593            and isinstance(self, Func)
594            and len(args) > len(self.arg_types)
595            and not self.is_var_len_args
596        ):
597            errors.append(
598                f"The number of provided arguments ({len(args)}) is greater than "
599                f"the maximum number of supported arguments ({len(self.arg_types)})"
600            )
601
602        return errors

Checks if this expression is valid (e.g. all mandatory args are set).

Arguments:
  • args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:

A list of error messages for all possible errors that were found.

def dump(self):
604    def dump(self):
605        """
606        Dump this Expression to a JSON-serializable dict.
607        """
608        from sqlglot.serde import dump
609
610        return dump(self)

Dump this Expression to a JSON-serializable dict.

@classmethod
def load(cls, obj):
612    @classmethod
613    def load(cls, obj):
614        """
615        Load a dict (as returned by `Expression.dump`) into an Expression instance.
616        """
617        from sqlglot.serde import load
618
619        return load(obj)

Load a dict (as returned by Expression.dump) into an Expression instance.

class Condition(Expression):
629class Condition(Expression):
630    def and_(self, *expressions, dialect=None, **opts):
631        """
632        AND this condition with one or multiple expressions.
633
634        Example:
635            >>> condition("x=1").and_("y=1").sql()
636            'x = 1 AND y = 1'
637
638        Args:
639            *expressions (str | Expression): the SQL code strings to parse.
640                If an `Expression` instance is passed, it will be used as-is.
641            dialect (str): the dialect used to parse the input expression.
642            opts (kwargs): other options to use to parse the input expressions.
643
644        Returns:
645            And: the new condition.
646        """
647        return and_(self, *expressions, dialect=dialect, **opts)
648
649    def or_(self, *expressions, dialect=None, **opts):
650        """
651        OR this condition with one or multiple expressions.
652
653        Example:
654            >>> condition("x=1").or_("y=1").sql()
655            'x = 1 OR y = 1'
656
657        Args:
658            *expressions (str | Expression): the SQL code strings to parse.
659                If an `Expression` instance is passed, it will be used as-is.
660            dialect (str): the dialect used to parse the input expression.
661            opts (kwargs): other options to use to parse the input expressions.
662
663        Returns:
664            Or: the new condition.
665        """
666        return or_(self, *expressions, dialect=dialect, **opts)
667
668    def not_(self):
669        """
670        Wrap this condition with NOT.
671
672        Example:
673            >>> condition("x=1").not_().sql()
674            'NOT x = 1'
675
676        Returns:
677            Not: the new condition.
678        """
679        return not_(self)
def and_(self, *expressions, dialect=None, **opts):
630    def and_(self, *expressions, dialect=None, **opts):
631        """
632        AND this condition with one or multiple expressions.
633
634        Example:
635            >>> condition("x=1").and_("y=1").sql()
636            'x = 1 AND y = 1'
637
638        Args:
639            *expressions (str | Expression): the SQL code strings to parse.
640                If an `Expression` instance is passed, it will be used as-is.
641            dialect (str): the dialect used to parse the input expression.
642            opts (kwargs): other options to use to parse the input expressions.
643
644        Returns:
645            And: the new condition.
646        """
647        return and_(self, *expressions, dialect=dialect, **opts)

AND this condition with one or multiple expressions.

Example:
>>> condition("x=1").and_("y=1").sql()
'x = 1 AND y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

And: the new condition.

def or_(self, *expressions, dialect=None, **opts):
649    def or_(self, *expressions, dialect=None, **opts):
650        """
651        OR this condition with one or multiple expressions.
652
653        Example:
654            >>> condition("x=1").or_("y=1").sql()
655            'x = 1 OR y = 1'
656
657        Args:
658            *expressions (str | Expression): the SQL code strings to parse.
659                If an `Expression` instance is passed, it will be used as-is.
660            dialect (str): the dialect used to parse the input expression.
661            opts (kwargs): other options to use to parse the input expressions.
662
663        Returns:
664            Or: the new condition.
665        """
666        return or_(self, *expressions, dialect=dialect, **opts)

OR this condition with one or multiple expressions.

Example:
>>> condition("x=1").or_("y=1").sql()
'x = 1 OR y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Or: the new condition.

def not_(self):
668    def not_(self):
669        """
670        Wrap this condition with NOT.
671
672        Example:
673            >>> condition("x=1").not_().sql()
674            'NOT x = 1'
675
676        Returns:
677            Not: the new condition.
678        """
679        return not_(self)

Wrap this condition with NOT.

Example:
>>> condition("x=1").not_().sql()
'NOT x = 1'
Returns:

Not: the new condition.

class Predicate(Condition):
682class Predicate(Condition):
683    """Relationships like x = y, x > 1, x >= y."""

Relationships like x = y, x > 1, x >= y.

class DerivedTable(Expression):
686class DerivedTable(Expression):
687    @property
688    def alias_column_names(self):
689        table_alias = self.args.get("alias")
690        if not table_alias:
691            return []
692        column_list = table_alias.assert_is(TableAlias).args.get("columns") or []
693        return [c.name for c in column_list]
694
695    @property
696    def selects(self):
697        alias = self.args.get("alias")
698
699        if alias:
700            return alias.columns
701        return []
702
703    @property
704    def named_selects(self):
705        return [select.output_name for select in self.selects]
class Unionable(Expression):
708class Unionable(Expression):
709    def union(self, expression, distinct=True, dialect=None, **opts):
710        """
711        Builds a UNION expression.
712
713        Example:
714            >>> import sqlglot
715            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
716            'SELECT * FROM foo UNION SELECT * FROM bla'
717
718        Args:
719            expression (str | Expression): the SQL code string.
720                If an `Expression` instance is passed, it will be used as-is.
721            distinct (bool): set the DISTINCT flag if and only if this is true.
722            dialect (str): the dialect used to parse the input expression.
723            opts (kwargs): other options to use to parse the input expressions.
724        Returns:
725            Union: the Union expression.
726        """
727        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
728
729    def intersect(self, expression, distinct=True, dialect=None, **opts):
730        """
731        Builds an INTERSECT expression.
732
733        Example:
734            >>> import sqlglot
735            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
736            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
737
738        Args:
739            expression (str | Expression): the SQL code string.
740                If an `Expression` instance is passed, it will be used as-is.
741            distinct (bool): set the DISTINCT flag if and only if this is true.
742            dialect (str): the dialect used to parse the input expression.
743            opts (kwargs): other options to use to parse the input expressions.
744        Returns:
745            Intersect: the Intersect expression
746        """
747        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
748
749    def except_(self, expression, distinct=True, dialect=None, **opts):
750        """
751        Builds an EXCEPT expression.
752
753        Example:
754            >>> import sqlglot
755            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
756            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
757
758        Args:
759            expression (str | Expression): the SQL code string.
760                If an `Expression` instance is passed, it will be used as-is.
761            distinct (bool): set the DISTINCT flag if and only if this is true.
762            dialect (str): the dialect used to parse the input expression.
763            opts (kwargs): other options to use to parse the input expressions.
764        Returns:
765            Except: the Except expression
766        """
767        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
def union(self, expression, distinct=True, dialect=None, **opts):
709    def union(self, expression, distinct=True, dialect=None, **opts):
710        """
711        Builds a UNION expression.
712
713        Example:
714            >>> import sqlglot
715            >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
716            'SELECT * FROM foo UNION SELECT * FROM bla'
717
718        Args:
719            expression (str | Expression): the SQL code string.
720                If an `Expression` instance is passed, it will be used as-is.
721            distinct (bool): set the DISTINCT flag if and only if this is true.
722            dialect (str): the dialect used to parse the input expression.
723            opts (kwargs): other options to use to parse the input expressions.
724        Returns:
725            Union: the Union expression.
726        """
727        return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds a UNION expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the Union expression.

def intersect(self, expression, distinct=True, dialect=None, **opts):
729    def intersect(self, expression, distinct=True, dialect=None, **opts):
730        """
731        Builds an INTERSECT expression.
732
733        Example:
734            >>> import sqlglot
735            >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
736            'SELECT * FROM foo INTERSECT SELECT * FROM bla'
737
738        Args:
739            expression (str | Expression): the SQL code string.
740                If an `Expression` instance is passed, it will be used as-is.
741            distinct (bool): set the DISTINCT flag if and only if this is true.
742            dialect (str): the dialect used to parse the input expression.
743            opts (kwargs): other options to use to parse the input expressions.
744        Returns:
745            Intersect: the Intersect expression
746        """
747        return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an INTERSECT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the Intersect expression

def except_(self, expression, distinct=True, dialect=None, **opts):
749    def except_(self, expression, distinct=True, dialect=None, **opts):
750        """
751        Builds an EXCEPT expression.
752
753        Example:
754            >>> import sqlglot
755            >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
756            'SELECT * FROM foo EXCEPT SELECT * FROM bla'
757
758        Args:
759            expression (str | Expression): the SQL code string.
760                If an `Expression` instance is passed, it will be used as-is.
761            distinct (bool): set the DISTINCT flag if and only if this is true.
762            dialect (str): the dialect used to parse the input expression.
763            opts (kwargs): other options to use to parse the input expressions.
764        Returns:
765            Except: the Except expression
766        """
767        return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)

Builds an EXCEPT expression.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • expression (str | Expression): the SQL code string. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the Except expression

class UDTF(DerivedTable, Unionable):
770class UDTF(DerivedTable, Unionable):
771    pass
class Cache(Expression):
774class Cache(Expression):
775    arg_types = {
776        "with": False,
777        "this": True,
778        "lazy": False,
779        "options": False,
780        "expression": False,
781    }
class Uncache(Expression):
784class Uncache(Expression):
785    arg_types = {"this": True, "exists": False}
class Create(Expression):
788class Create(Expression):
789    arg_types = {
790        "with": False,
791        "this": True,
792        "kind": True,
793        "expression": False,
794        "exists": False,
795        "properties": False,
796        "replace": False,
797        "unique": False,
798        "indexes": False,
799        "no_schema_binding": False,
800        "begin": False,
801    }
class Describe(Expression):
804class Describe(Expression):
805    arg_types = {"this": True, "kind": False}
class Set(Expression):
808class Set(Expression):
809    arg_types = {"expressions": True}
class SetItem(Expression):
812class SetItem(Expression):
813    arg_types = {
814        "this": False,
815        "expressions": False,
816        "kind": False,
817        "collate": False,  # MySQL SET NAMES statement
818        "global": False,
819    }
class Show(Expression):
822class Show(Expression):
823    arg_types = {
824        "this": True,
825        "target": False,
826        "offset": False,
827        "limit": False,
828        "like": False,
829        "where": False,
830        "db": False,
831        "full": False,
832        "mutex": False,
833        "query": False,
834        "channel": False,
835        "global": False,
836        "log": False,
837        "position": False,
838        "types": False,
839    }
class UserDefinedFunction(Expression):
842class UserDefinedFunction(Expression):
843    arg_types = {"this": True, "expressions": False, "wrapped": False}
class CharacterSet(Expression):
846class CharacterSet(Expression):
847    arg_types = {"this": True, "default": False}
class With(Expression):
850class With(Expression):
851    arg_types = {"expressions": True, "recursive": False}
852
853    @property
854    def recursive(self) -> bool:
855        return bool(self.args.get("recursive"))
class WithinGroup(Expression):
858class WithinGroup(Expression):
859    arg_types = {"this": True, "expression": False}
class CTE(DerivedTable):
862class CTE(DerivedTable):
863    arg_types = {"this": True, "alias": True}
class TableAlias(Expression):
866class TableAlias(Expression):
867    arg_types = {"this": False, "columns": False}
868
869    @property
870    def columns(self):
871        return self.args.get("columns") or []
class BitString(Condition):
874class BitString(Condition):
875    pass
class HexString(Condition):
878class HexString(Condition):
879    pass
class ByteString(Condition):
882class ByteString(Condition):
883    pass
class Column(Condition):
886class Column(Condition):
887    arg_types = {"this": True, "table": False, "db": False, "catalog": False}
888
889    @property
890    def table(self) -> str:
891        return self.text("table")
892
893    @property
894    def db(self) -> str:
895        return self.text("db")
896
897    @property
898    def catalog(self) -> str:
899        return self.text("catalog")
900
901    @property
902    def output_name(self) -> str:
903        return self.name
output_name: str

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class ColumnDef(Expression):
906class ColumnDef(Expression):
907    arg_types = {
908        "this": True,
909        "kind": False,
910        "constraints": False,
911        "exists": False,
912    }
class AlterColumn(Expression):
915class AlterColumn(Expression):
916    arg_types = {
917        "this": True,
918        "dtype": False,
919        "collate": False,
920        "using": False,
921        "default": False,
922        "drop": False,
923    }
class RenameTable(Expression):
926class RenameTable(Expression):
927    pass
class ColumnConstraint(Expression):
930class ColumnConstraint(Expression):
931    arg_types = {"this": False, "kind": True}
class ColumnConstraintKind(Expression):
934class ColumnConstraintKind(Expression):
935    pass
class AutoIncrementColumnConstraint(ColumnConstraintKind):
938class AutoIncrementColumnConstraint(ColumnConstraintKind):
939    pass
class CaseSpecificColumnConstraint(ColumnConstraintKind):
942class CaseSpecificColumnConstraint(ColumnConstraintKind):
943    arg_types = {"not_": True}
class CharacterSetColumnConstraint(ColumnConstraintKind):
946class CharacterSetColumnConstraint(ColumnConstraintKind):
947    arg_types = {"this": True}
class CheckColumnConstraint(ColumnConstraintKind):
950class CheckColumnConstraint(ColumnConstraintKind):
951    pass
class CollateColumnConstraint(ColumnConstraintKind):
954class CollateColumnConstraint(ColumnConstraintKind):
955    pass
class CommentColumnConstraint(ColumnConstraintKind):
958class CommentColumnConstraint(ColumnConstraintKind):
959    pass
class CompressColumnConstraint(ColumnConstraintKind):
962class CompressColumnConstraint(ColumnConstraintKind):
963    pass
class DateFormatColumnConstraint(ColumnConstraintKind):
966class DateFormatColumnConstraint(ColumnConstraintKind):
967    arg_types = {"this": True}
class DefaultColumnConstraint(ColumnConstraintKind):
970class DefaultColumnConstraint(ColumnConstraintKind):
971    pass
class EncodeColumnConstraint(ColumnConstraintKind):
974class EncodeColumnConstraint(ColumnConstraintKind):
975    pass
class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
978class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind):
979    # this: True -> ALWAYS, this: False -> BY DEFAULT
980    arg_types = {
981        "this": False,
982        "start": False,
983        "increment": False,
984        "minvalue": False,
985        "maxvalue": False,
986        "cycle": False,
987    }
class InlineLengthColumnConstraint(ColumnConstraintKind):
990class InlineLengthColumnConstraint(ColumnConstraintKind):
991    pass
class NotNullColumnConstraint(ColumnConstraintKind):
994class NotNullColumnConstraint(ColumnConstraintKind):
995    arg_types = {"allow_null": False}
class PrimaryKeyColumnConstraint(ColumnConstraintKind):
998class PrimaryKeyColumnConstraint(ColumnConstraintKind):
999    arg_types = {"desc": False}
class TitleColumnConstraint(ColumnConstraintKind):
1002class TitleColumnConstraint(ColumnConstraintKind):
1003    pass
class UniqueColumnConstraint(ColumnConstraintKind):
1006class UniqueColumnConstraint(ColumnConstraintKind):
1007    arg_types: t.Dict[str, t.Any] = {}
class UppercaseColumnConstraint(ColumnConstraintKind):
1010class UppercaseColumnConstraint(ColumnConstraintKind):
1011    arg_types: t.Dict[str, t.Any] = {}
class PathColumnConstraint(ColumnConstraintKind):
1014class PathColumnConstraint(ColumnConstraintKind):
1015    pass
class Constraint(Expression):
1018class Constraint(Expression):
1019    arg_types = {"this": True, "expressions": True}
class Delete(Expression):
1022class Delete(Expression):
1023    arg_types = {"with": False, "this": False, "using": False, "where": False}
class Drop(Expression):
1026class Drop(Expression):
1027    arg_types = {
1028        "this": False,
1029        "kind": False,
1030        "exists": False,
1031        "temporary": False,
1032        "materialized": False,
1033        "cascade": False,
1034    }
class Filter(Expression):
1037class Filter(Expression):
1038    arg_types = {"this": True, "expression": True}
class Check(Expression):
1041class Check(Expression):
1042    pass
class Directory(Expression):
1045class Directory(Expression):
1046    # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html
1047    arg_types = {"this": True, "local": False, "row_format": False}
class ForeignKey(Expression):
1050class ForeignKey(Expression):
1051    arg_types = {
1052        "expressions": True,
1053        "reference": False,
1054        "delete": False,
1055        "update": False,
1056    }
class PrimaryKey(Expression):
1059class PrimaryKey(Expression):
1060    arg_types = {"expressions": True, "options": False}
class Unique(Expression):
1063class Unique(Expression):
1064    arg_types = {"expressions": True}
class Into(Expression):
1069class Into(Expression):
1070    arg_types = {"this": True, "temporary": False, "unlogged": False}
class From(Expression):
1073class From(Expression):
1074    arg_types = {"expressions": True}
class Having(Expression):
1077class Having(Expression):
1078    pass
class Hint(Expression):
1081class Hint(Expression):
1082    arg_types = {"expressions": True}
class JoinHint(Expression):
1085class JoinHint(Expression):
1086    arg_types = {"this": True, "expressions": True}
class Identifier(Expression):
1089class Identifier(Expression):
1090    arg_types = {"this": True, "quoted": False}
1091
1092    @property
1093    def quoted(self):
1094        return bool(self.args.get("quoted"))
1095
1096    def __eq__(self, other):
1097        return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this)
1098
1099    def __hash__(self):
1100        return hash((self.key, self.this.lower()))
1101
1102    @property
1103    def output_name(self):
1104        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Index(Expression):
1107class Index(Expression):
1108    arg_types = {
1109        "this": False,
1110        "table": False,
1111        "where": False,
1112        "columns": False,
1113        "unique": False,
1114        "primary": False,
1115        "amp": False,  # teradata
1116    }
class Insert(Expression):
1119class Insert(Expression):
1120    arg_types = {
1121        "with": False,
1122        "this": True,
1123        "expression": False,
1124        "overwrite": False,
1125        "exists": False,
1126        "partition": False,
1127        "alternative": False,
1128    }
class Introducer(Expression):
1132class Introducer(Expression):
1133    arg_types = {"this": True, "expression": True}
class National(Expression):
1137class National(Expression):
1138    pass
class LoadData(Expression):
1141class LoadData(Expression):
1142    arg_types = {
1143        "this": True,
1144        "local": False,
1145        "overwrite": False,
1146        "inpath": True,
1147        "partition": False,
1148        "input_format": False,
1149        "serde": False,
1150    }
class Partition(Expression):
1153class Partition(Expression):
1154    arg_types = {"expressions": True}
class Fetch(Expression):
1157class Fetch(Expression):
1158    arg_types = {"direction": False, "count": False}
class Group(Expression):
1161class Group(Expression):
1162    arg_types = {
1163        "expressions": False,
1164        "grouping_sets": False,
1165        "cube": False,
1166        "rollup": False,
1167    }
class Lambda(Expression):
1170class Lambda(Expression):
1171    arg_types = {"this": True, "expressions": True}
class Limit(Expression):
1174class Limit(Expression):
1175    arg_types = {"this": False, "expression": True}
class Literal(Condition):
1178class Literal(Condition):
1179    arg_types = {"this": True, "is_string": True}
1180
1181    def __eq__(self, other):
1182        return (
1183            isinstance(other, Literal)
1184            and self.this == other.this
1185            and self.args["is_string"] == other.args["is_string"]
1186        )
1187
1188    def __hash__(self):
1189        return hash((self.key, self.this, self.args["is_string"]))
1190
1191    @classmethod
1192    def number(cls, number) -> Literal:
1193        return cls(this=str(number), is_string=False)
1194
1195    @classmethod
1196    def string(cls, string) -> Literal:
1197        return cls(this=str(string), is_string=True)
1198
1199    @property
1200    def output_name(self):
1201        return self.name
@classmethod
def number(cls, number) -> sqlglot.expressions.Literal:
1191    @classmethod
1192    def number(cls, number) -> Literal:
1193        return cls(this=str(number), is_string=False)
@classmethod
def string(cls, string) -> sqlglot.expressions.Literal:
1195    @classmethod
1196    def string(cls, string) -> Literal:
1197        return cls(this=str(string), is_string=True)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Join(Expression):
1204class Join(Expression):
1205    arg_types = {
1206        "this": True,
1207        "on": False,
1208        "side": False,
1209        "kind": False,
1210        "using": False,
1211        "natural": False,
1212    }
1213
1214    @property
1215    def kind(self):
1216        return self.text("kind").upper()
1217
1218    @property
1219    def side(self):
1220        return self.text("side").upper()
1221
1222    @property
1223    def alias_or_name(self):
1224        return self.this.alias_or_name
1225
1226    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1227        """
1228        Append to or set the ON expressions.
1229
1230        Example:
1231            >>> import sqlglot
1232            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1233            'JOIN x ON y = 1'
1234
1235        Args:
1236            *expressions (str | Expression): the SQL code strings to parse.
1237                If an `Expression` instance is passed, it will be used as-is.
1238                Multiple expressions are combined with an AND operator.
1239            append (bool): if `True`, AND the new expressions to any existing expression.
1240                Otherwise, this resets the expression.
1241            dialect (str): the dialect used to parse the input expressions.
1242            copy (bool): if `False`, modify this expression instance in-place.
1243            opts (kwargs): other options to use to parse the input expressions.
1244
1245        Returns:
1246            Join: the modified join expression.
1247        """
1248        join = _apply_conjunction_builder(
1249            *expressions,
1250            instance=self,
1251            arg="on",
1252            append=append,
1253            dialect=dialect,
1254            copy=copy,
1255            **opts,
1256        )
1257
1258        if join.kind == "CROSS":
1259            join.set("kind", None)
1260
1261        return join
1262
1263    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1264        """
1265        Append to or set the USING expressions.
1266
1267        Example:
1268            >>> import sqlglot
1269            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1270            'JOIN x USING (foo, bla)'
1271
1272        Args:
1273            *expressions (str | Expression): the SQL code strings to parse.
1274                If an `Expression` instance is passed, it will be used as-is.
1275            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1276                Otherwise, this resets the expression.
1277            dialect (str): the dialect used to parse the input expressions.
1278            copy (bool): if `False`, modify this expression instance in-place.
1279            opts (kwargs): other options to use to parse the input expressions.
1280
1281        Returns:
1282            Join: the modified join expression.
1283        """
1284        join = _apply_list_builder(
1285            *expressions,
1286            instance=self,
1287            arg="using",
1288            append=append,
1289            dialect=dialect,
1290            copy=copy,
1291            **opts,
1292        )
1293
1294        if join.kind == "CROSS":
1295            join.set("kind", None)
1296
1297        return join
def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1226    def on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1227        """
1228        Append to or set the ON expressions.
1229
1230        Example:
1231            >>> import sqlglot
1232            >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
1233            'JOIN x ON y = 1'
1234
1235        Args:
1236            *expressions (str | Expression): the SQL code strings to parse.
1237                If an `Expression` instance is passed, it will be used as-is.
1238                Multiple expressions are combined with an AND operator.
1239            append (bool): if `True`, AND the new expressions to any existing expression.
1240                Otherwise, this resets the expression.
1241            dialect (str): the dialect used to parse the input expressions.
1242            copy (bool): if `False`, modify this expression instance in-place.
1243            opts (kwargs): other options to use to parse the input expressions.
1244
1245        Returns:
1246            Join: the modified join expression.
1247        """
1248        join = _apply_conjunction_builder(
1249            *expressions,
1250            instance=self,
1251            arg="on",
1252            append=append,
1253            dialect=dialect,
1254            copy=copy,
1255            **opts,
1256        )
1257
1258        if join.kind == "CROSS":
1259            join.set("kind", None)
1260
1261        return join

Append to or set the ON expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql()
'JOIN x ON y = 1'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1263    def using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1264        """
1265        Append to or set the USING expressions.
1266
1267        Example:
1268            >>> import sqlglot
1269            >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
1270            'JOIN x USING (foo, bla)'
1271
1272        Args:
1273            *expressions (str | Expression): the SQL code strings to parse.
1274                If an `Expression` instance is passed, it will be used as-is.
1275            append (bool): if `True`, concatenate the new expressions to the existing "using" list.
1276                Otherwise, this resets the expression.
1277            dialect (str): the dialect used to parse the input expressions.
1278            copy (bool): if `False`, modify this expression instance in-place.
1279            opts (kwargs): other options to use to parse the input expressions.
1280
1281        Returns:
1282            Join: the modified join expression.
1283        """
1284        join = _apply_list_builder(
1285            *expressions,
1286            instance=self,
1287            arg="using",
1288            append=append,
1289            dialect=dialect,
1290            copy=copy,
1291            **opts,
1292        )
1293
1294        if join.kind == "CROSS":
1295            join.set("kind", None)
1296
1297        return join

Append to or set the USING expressions.

Example:
>>> import sqlglot
>>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql()
'JOIN x USING (foo, bla)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Join: the modified join expression.

class Lateral(UDTF):
1300class Lateral(UDTF):
1301    arg_types = {"this": True, "view": False, "outer": False, "alias": False}
class MatchRecognize(Expression):
1304class MatchRecognize(Expression):
1305    arg_types = {
1306        "partition_by": False,
1307        "order": False,
1308        "measures": False,
1309        "rows": False,
1310        "after": False,
1311        "pattern": False,
1312        "define": False,
1313    }
class Final(Expression):
1318class Final(Expression):
1319    pass
class Offset(Expression):
1322class Offset(Expression):
1323    arg_types = {"this": False, "expression": True}
class Order(Expression):
1326class Order(Expression):
1327    arg_types = {"this": False, "expressions": True}
class Cluster(Order):
1332class Cluster(Order):
1333    pass
class Distribute(Order):
1336class Distribute(Order):
1337    pass
class Sort(Order):
1340class Sort(Order):
1341    pass
class Ordered(Expression):
1344class Ordered(Expression):
1345    arg_types = {"this": True, "desc": True, "nulls_first": True}
class Property(Expression):
1348class Property(Expression):
1349    arg_types = {"this": True, "value": True}
class AfterJournalProperty(Property):
1352class AfterJournalProperty(Property):
1353    arg_types = {"no": True, "dual": False, "local": False}
class AlgorithmProperty(Property):
1356class AlgorithmProperty(Property):
1357    arg_types = {"this": True}
class AutoIncrementProperty(Property):
1360class AutoIncrementProperty(Property):
1361    arg_types = {"this": True}
class BlockCompressionProperty(Property):
1364class BlockCompressionProperty(Property):
1365    arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
class CharacterSetProperty(Property):
1368class CharacterSetProperty(Property):
1369    arg_types = {"this": True, "default": True}
class ChecksumProperty(Property):
1372class ChecksumProperty(Property):
1373    arg_types = {"on": False, "default": False}
class CollateProperty(Property):
1376class CollateProperty(Property):
1377    arg_types = {"this": True}
class DataBlocksizeProperty(Property):
1380class DataBlocksizeProperty(Property):
1381    arg_types = {"size": False, "units": False, "min": False, "default": False}
class DefinerProperty(Property):
1384class DefinerProperty(Property):
1385    arg_types = {"this": True}
class DistKeyProperty(Property):
1388class DistKeyProperty(Property):
1389    arg_types = {"this": True}
class DistStyleProperty(Property):
1392class DistStyleProperty(Property):
1393    arg_types = {"this": True}
class EngineProperty(Property):
1396class EngineProperty(Property):
1397    arg_types = {"this": True}
class ExecuteAsProperty(Property):
1400class ExecuteAsProperty(Property):
1401    arg_types = {"this": True}
class ExternalProperty(Property):
1404class ExternalProperty(Property):
1405    arg_types = {"this": False}
class FallbackProperty(Property):
1408class FallbackProperty(Property):
1409    arg_types = {"no": True, "protection": False}
class FileFormatProperty(Property):
1412class FileFormatProperty(Property):
1413    arg_types = {"this": True}
class FreespaceProperty(Property):
1416class FreespaceProperty(Property):
1417    arg_types = {"this": True, "percent": False}
class IsolatedLoadingProperty(Property):
1420class IsolatedLoadingProperty(Property):
1421    arg_types = {
1422        "no": True,
1423        "concurrent": True,
1424        "for_all": True,
1425        "for_insert": True,
1426        "for_none": True,
1427    }
class JournalProperty(Property):
1430class JournalProperty(Property):
1431    arg_types = {"no": True, "dual": False, "before": False}
class LanguageProperty(Property):
1434class LanguageProperty(Property):
1435    arg_types = {"this": True}
class LikeProperty(Property):
1438class LikeProperty(Property):
1439    arg_types = {"this": True, "expressions": False}
class LocationProperty(Property):
1442class LocationProperty(Property):
1443    arg_types = {"this": True}
class LockingProperty(Property):
1446class LockingProperty(Property):
1447    arg_types = {
1448        "this": False,
1449        "kind": True,
1450        "for_or_in": True,
1451        "lock_type": True,
1452        "override": False,
1453    }
class LogProperty(Property):
1456class LogProperty(Property):
1457    arg_types = {"no": True}
class MaterializedProperty(Property):
1460class MaterializedProperty(Property):
1461    arg_types = {"this": False}
class MergeBlockRatioProperty(Property):
1464class MergeBlockRatioProperty(Property):
1465    arg_types = {"this": False, "no": False, "default": False, "percent": False}
class NoPrimaryIndexProperty(Property):
1468class NoPrimaryIndexProperty(Property):
1469    arg_types = {"this": False}
class OnCommitProperty(Property):
1472class OnCommitProperty(Property):
1473    arg_type = {"this": False}
class PartitionedByProperty(Property):
1476class PartitionedByProperty(Property):
1477    arg_types = {"this": True}
class ReturnsProperty(Property):
1480class ReturnsProperty(Property):
1481    arg_types = {"this": True, "is_table": False, "table": False}
class RowFormatDelimitedProperty(Property):
1484class RowFormatDelimitedProperty(Property):
1485    # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml
1486    arg_types = {
1487        "fields": False,
1488        "escaped": False,
1489        "collection_items": False,
1490        "map_keys": False,
1491        "lines": False,
1492        "null": False,
1493        "serde": False,
1494    }
class RowFormatSerdeProperty(Property):
1497class RowFormatSerdeProperty(Property):
1498    arg_types = {"this": True}
class SchemaCommentProperty(Property):
1501class SchemaCommentProperty(Property):
1502    arg_types = {"this": True}
class SerdeProperties(Property):
1505class SerdeProperties(Property):
1506    arg_types = {"expressions": True}
class SetProperty(Property):
1509class SetProperty(Property):
1510    arg_types = {"multi": True}
class SortKeyProperty(Property):
1513class SortKeyProperty(Property):
1514    arg_types = {"this": True, "compound": False}
class SqlSecurityProperty(Property):
1517class SqlSecurityProperty(Property):
1518    arg_types = {"definer": True}
class TableFormatProperty(Property):
1521class TableFormatProperty(Property):
1522    arg_types = {"this": True}
class TemporaryProperty(Property):
1525class TemporaryProperty(Property):
1526    arg_types = {"global_": True}
class TransientProperty(Property):
1529class TransientProperty(Property):
1530    arg_types = {"this": False}
class VolatilityProperty(Property):
1533class VolatilityProperty(Property):
1534    arg_types = {"this": True}
class WithDataProperty(Property):
1537class WithDataProperty(Property):
1538    arg_types = {"no": True, "statistics": False}
class WithJournalTableProperty(Property):
1541class WithJournalTableProperty(Property):
1542    arg_types = {"this": True}
class Properties(Expression):
1545class Properties(Expression):
1546    arg_types = {"expressions": True}
1547
1548    NAME_TO_PROPERTY = {
1549        "ALGORITHM": AlgorithmProperty,
1550        "AUTO_INCREMENT": AutoIncrementProperty,
1551        "CHARACTER SET": CharacterSetProperty,
1552        "COLLATE": CollateProperty,
1553        "COMMENT": SchemaCommentProperty,
1554        "DEFINER": DefinerProperty,
1555        "DISTKEY": DistKeyProperty,
1556        "DISTSTYLE": DistStyleProperty,
1557        "ENGINE": EngineProperty,
1558        "EXECUTE AS": ExecuteAsProperty,
1559        "FORMAT": FileFormatProperty,
1560        "LANGUAGE": LanguageProperty,
1561        "LOCATION": LocationProperty,
1562        "PARTITIONED_BY": PartitionedByProperty,
1563        "RETURNS": ReturnsProperty,
1564        "SORTKEY": SortKeyProperty,
1565        "TABLE_FORMAT": TableFormatProperty,
1566    }
1567
1568    PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()}
1569
1570    # CREATE property locations
1571    # Form: schema specified
1572    #   create [POST_CREATE]
1573    #     table a [POST_NAME]
1574    #     (b int) [POST_SCHEMA]
1575    #     with ([POST_WITH])
1576    #     index (b) [POST_INDEX]
1577    #
1578    # Form: alias selection
1579    #   create [POST_CREATE]
1580    #     table a [POST_NAME]
1581    #     as [POST_ALIAS] (select * from b) [POST_EXPRESSION]
1582    #     index (c) [POST_INDEX]
1583    class Location(AutoName):
1584        POST_CREATE = auto()
1585        POST_NAME = auto()
1586        POST_SCHEMA = auto()
1587        POST_WITH = auto()
1588        POST_ALIAS = auto()
1589        POST_EXPRESSION = auto()
1590        POST_INDEX = auto()
1591        UNSUPPORTED = auto()
1592
1593    @classmethod
1594    def from_dict(cls, properties_dict) -> Properties:
1595        expressions = []
1596        for key, value in properties_dict.items():
1597            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1598            if property_cls:
1599                expressions.append(property_cls(this=convert(value)))
1600            else:
1601                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1602
1603        return cls(expressions=expressions)
@classmethod
def from_dict(cls, properties_dict) -> sqlglot.expressions.Properties:
1593    @classmethod
1594    def from_dict(cls, properties_dict) -> Properties:
1595        expressions = []
1596        for key, value in properties_dict.items():
1597            property_cls = cls.NAME_TO_PROPERTY.get(key.upper())
1598            if property_cls:
1599                expressions.append(property_cls(this=convert(value)))
1600            else:
1601                expressions.append(Property(this=Literal.string(key), value=convert(value)))
1602
1603        return cls(expressions=expressions)
class Properties.Location(sqlglot.helper.AutoName):
1583    class Location(AutoName):
1584        POST_CREATE = auto()
1585        POST_NAME = auto()
1586        POST_SCHEMA = auto()
1587        POST_WITH = auto()
1588        POST_ALIAS = auto()
1589        POST_EXPRESSION = auto()
1590        POST_INDEX = auto()
1591        UNSUPPORTED = auto()

An enumeration.

POST_CREATE = <Location.POST_CREATE: 'POST_CREATE'>
POST_NAME = <Location.POST_NAME: 'POST_NAME'>
POST_SCHEMA = <Location.POST_SCHEMA: 'POST_SCHEMA'>
POST_WITH = <Location.POST_WITH: 'POST_WITH'>
POST_ALIAS = <Location.POST_ALIAS: 'POST_ALIAS'>
POST_EXPRESSION = <Location.POST_EXPRESSION: 'POST_EXPRESSION'>
POST_INDEX = <Location.POST_INDEX: 'POST_INDEX'>
UNSUPPORTED = <Location.UNSUPPORTED: 'UNSUPPORTED'>
Inherited Members
enum.Enum
name
value
class Qualify(Expression):
1606class Qualify(Expression):
1607    pass
class Return(Expression):
1611class Return(Expression):
1612    pass
class Reference(Expression):
1615class Reference(Expression):
1616    arg_types = {"this": True, "expressions": False, "options": False}
class Tuple(Expression):
1619class Tuple(Expression):
1620    arg_types = {"expressions": False}
class Subqueryable(Unionable):
1623class Subqueryable(Unionable):
1624    def subquery(self, alias=None, copy=True) -> Subquery:
1625        """
1626        Convert this expression to an aliased expression that can be used as a Subquery.
1627
1628        Example:
1629            >>> subquery = Select().select("x").from_("tbl").subquery()
1630            >>> Select().select("x").from_(subquery).sql()
1631            'SELECT x FROM (SELECT x FROM tbl)'
1632
1633        Args:
1634            alias (str | Identifier): an optional alias for the subquery
1635            copy (bool): if `False`, modify this expression instance in-place.
1636
1637        Returns:
1638            Alias: the subquery
1639        """
1640        instance = _maybe_copy(self, copy)
1641        return Subquery(
1642            this=instance,
1643            alias=TableAlias(this=to_identifier(alias)),
1644        )
1645
1646    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1647        raise NotImplementedError
1648
1649    @property
1650    def ctes(self):
1651        with_ = self.args.get("with")
1652        if not with_:
1653            return []
1654        return with_.expressions
1655
1656    @property
1657    def selects(self):
1658        raise NotImplementedError("Subqueryable objects must implement `selects`")
1659
1660    @property
1661    def named_selects(self):
1662        raise NotImplementedError("Subqueryable objects must implement `named_selects`")
1663
1664    def with_(
1665        self,
1666        alias,
1667        as_,
1668        recursive=None,
1669        append=True,
1670        dialect=None,
1671        copy=True,
1672        **opts,
1673    ):
1674        """
1675        Append to or set the common table expressions.
1676
1677        Example:
1678            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1679            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1680
1681        Args:
1682            alias (str | Expression): the SQL code string to parse as the table name.
1683                If an `Expression` instance is passed, this is used as-is.
1684            as_ (str | Expression): the SQL code string to parse as the table expression.
1685                If an `Expression` instance is passed, it will be used as-is.
1686            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1687            append (bool): if `True`, add to any existing expressions.
1688                Otherwise, this resets the expressions.
1689            dialect (str): the dialect used to parse the input expression.
1690            copy (bool): if `False`, modify this expression instance in-place.
1691            opts (kwargs): other options to use to parse the input expressions.
1692
1693        Returns:
1694            Select: the modified expression.
1695        """
1696        alias_expression = maybe_parse(
1697            alias,
1698            dialect=dialect,
1699            into=TableAlias,
1700            **opts,
1701        )
1702        as_expression = maybe_parse(
1703            as_,
1704            dialect=dialect,
1705            **opts,
1706        )
1707        cte = CTE(
1708            this=as_expression,
1709            alias=alias_expression,
1710        )
1711        return _apply_child_list_builder(
1712            cte,
1713            instance=self,
1714            arg="with",
1715            append=append,
1716            copy=copy,
1717            into=With,
1718            properties={"recursive": recursive or False},
1719        )
def subquery(self, alias=None, copy=True) -> sqlglot.expressions.Subquery:
1624    def subquery(self, alias=None, copy=True) -> Subquery:
1625        """
1626        Convert this expression to an aliased expression that can be used as a Subquery.
1627
1628        Example:
1629            >>> subquery = Select().select("x").from_("tbl").subquery()
1630            >>> Select().select("x").from_(subquery).sql()
1631            'SELECT x FROM (SELECT x FROM tbl)'
1632
1633        Args:
1634            alias (str | Identifier): an optional alias for the subquery
1635            copy (bool): if `False`, modify this expression instance in-place.
1636
1637        Returns:
1638            Alias: the subquery
1639        """
1640        instance = _maybe_copy(self, copy)
1641        return Subquery(
1642            this=instance,
1643            alias=TableAlias(this=to_identifier(alias)),
1644        )

Convert this expression to an aliased expression that can be used as a Subquery.

Example:
>>> subquery = Select().select("x").from_("tbl").subquery()
>>> Select().select("x").from_(subquery).sql()
'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
  • alias (str | Identifier): an optional alias for the subquery
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Alias: the subquery

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1646    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1647        raise NotImplementedError
def with_( self, alias, as_, recursive=None, append=True, dialect=None, copy=True, **opts):
1664    def with_(
1665        self,
1666        alias,
1667        as_,
1668        recursive=None,
1669        append=True,
1670        dialect=None,
1671        copy=True,
1672        **opts,
1673    ):
1674        """
1675        Append to or set the common table expressions.
1676
1677        Example:
1678            >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
1679            'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
1680
1681        Args:
1682            alias (str | Expression): the SQL code string to parse as the table name.
1683                If an `Expression` instance is passed, this is used as-is.
1684            as_ (str | Expression): the SQL code string to parse as the table expression.
1685                If an `Expression` instance is passed, it will be used as-is.
1686            recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`.
1687            append (bool): if `True`, add to any existing expressions.
1688                Otherwise, this resets the expressions.
1689            dialect (str): the dialect used to parse the input expression.
1690            copy (bool): if `False`, modify this expression instance in-place.
1691            opts (kwargs): other options to use to parse the input expressions.
1692
1693        Returns:
1694            Select: the modified expression.
1695        """
1696        alias_expression = maybe_parse(
1697            alias,
1698            dialect=dialect,
1699            into=TableAlias,
1700            **opts,
1701        )
1702        as_expression = maybe_parse(
1703            as_,
1704            dialect=dialect,
1705            **opts,
1706        )
1707        cte = CTE(
1708            this=as_expression,
1709            alias=alias_expression,
1710        )
1711        return _apply_child_list_builder(
1712            cte,
1713            instance=self,
1714            arg="with",
1715            append=append,
1716            copy=copy,
1717            into=With,
1718            properties={"recursive": recursive or False},
1719        )

Append to or set the common table expressions.

Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql()
'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
  • alias (str | Expression): the SQL code string to parse as the table name. If an Expression instance is passed, this is used as-is.
  • as_ (str | Expression): the SQL code string to parse as the table expression. If an Expression instance is passed, it will be used as-is.
  • recursive (bool): set the RECURSIVE part of the expression. Defaults to False.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

class Table(Expression):
1742class Table(Expression):
1743    arg_types = {
1744        "this": True,
1745        "alias": False,
1746        "db": False,
1747        "catalog": False,
1748        "laterals": False,
1749        "joins": False,
1750        "pivots": False,
1751        "hints": False,
1752        "system_time": False,
1753    }
1754
1755    @property
1756    def db(self) -> str:
1757        return self.text("db")
1758
1759    @property
1760    def catalog(self) -> str:
1761        return self.text("catalog")
class SystemTime(Expression):
1765class SystemTime(Expression):
1766    arg_types = {
1767        "this": False,
1768        "expression": False,
1769        "kind": True,
1770    }
class Union(Subqueryable):
1773class Union(Subqueryable):
1774    arg_types = {
1775        "with": False,
1776        "this": True,
1777        "expression": True,
1778        "distinct": False,
1779        **QUERY_MODIFIERS,
1780    }
1781
1782    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1783        """
1784        Set the LIMIT expression.
1785
1786        Example:
1787            >>> select("1").union(select("1")).limit(1).sql()
1788            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1789
1790        Args:
1791            expression (str | int | Expression): the SQL code string to parse.
1792                This can also be an integer.
1793                If a `Limit` instance is passed, this is used as-is.
1794                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1795            dialect (str): the dialect used to parse the input expression.
1796            copy (bool): if `False`, modify this expression instance in-place.
1797            opts (kwargs): other options to use to parse the input expressions.
1798
1799        Returns:
1800            Select: The limited subqueryable.
1801        """
1802        return (
1803            select("*")
1804            .from_(self.subquery(alias="_l_0", copy=copy))
1805            .limit(expression, dialect=dialect, copy=False, **opts)
1806        )
1807
1808    def select(
1809        self,
1810        *expressions: str | Expression,
1811        append: bool = True,
1812        dialect: DialectType = None,
1813        copy: bool = True,
1814        **opts,
1815    ) -> Union:
1816        """Append to or set the SELECT of the union recursively.
1817
1818        Example:
1819            >>> from sqlglot import parse_one
1820            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1821            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1822
1823        Args:
1824            *expressions: the SQL code strings to parse.
1825                If an `Expression` instance is passed, it will be used as-is.
1826            append: if `True`, add to any existing expressions.
1827                Otherwise, this resets the expressions.
1828            dialect: the dialect used to parse the input expressions.
1829            copy: if `False`, modify this expression instance in-place.
1830            opts: other options to use to parse the input expressions.
1831
1832        Returns:
1833            Union: the modified expression.
1834        """
1835        this = self.copy() if copy else self
1836        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1837        this.expression.unnest().select(
1838            *expressions, append=append, dialect=dialect, copy=False, **opts
1839        )
1840        return this
1841
1842    @property
1843    def named_selects(self):
1844        return self.this.unnest().named_selects
1845
1846    @property
1847    def is_star(self) -> bool:
1848        return self.this.is_star or self.expression.is_star
1849
1850    @property
1851    def selects(self):
1852        return self.this.unnest().selects
1853
1854    @property
1855    def left(self):
1856        return self.this
1857
1858    @property
1859    def right(self):
1860        return self.expression
def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1782    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
1783        """
1784        Set the LIMIT expression.
1785
1786        Example:
1787            >>> select("1").union(select("1")).limit(1).sql()
1788            'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
1789
1790        Args:
1791            expression (str | int | Expression): the SQL code string to parse.
1792                This can also be an integer.
1793                If a `Limit` instance is passed, this is used as-is.
1794                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
1795            dialect (str): the dialect used to parse the input expression.
1796            copy (bool): if `False`, modify this expression instance in-place.
1797            opts (kwargs): other options to use to parse the input expressions.
1798
1799        Returns:
1800            Select: The limited subqueryable.
1801        """
1802        return (
1803            select("*")
1804            .from_(self.subquery(alias="_l_0", copy=copy))
1805            .limit(expression, dialect=dialect, copy=False, **opts)
1806        )

Set the LIMIT expression.

Example:
>>> select("1").union(select("1")).limit(1).sql()
'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: The limited subqueryable.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Union:
1808    def select(
1809        self,
1810        *expressions: str | Expression,
1811        append: bool = True,
1812        dialect: DialectType = None,
1813        copy: bool = True,
1814        **opts,
1815    ) -> Union:
1816        """Append to or set the SELECT of the union recursively.
1817
1818        Example:
1819            >>> from sqlglot import parse_one
1820            >>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
1821            'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
1822
1823        Args:
1824            *expressions: the SQL code strings to parse.
1825                If an `Expression` instance is passed, it will be used as-is.
1826            append: if `True`, add to any existing expressions.
1827                Otherwise, this resets the expressions.
1828            dialect: the dialect used to parse the input expressions.
1829            copy: if `False`, modify this expression instance in-place.
1830            opts: other options to use to parse the input expressions.
1831
1832        Returns:
1833            Union: the modified expression.
1834        """
1835        this = self.copy() if copy else self
1836        this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts)
1837        this.expression.unnest().select(
1838            *expressions, append=append, dialect=dialect, copy=False, **opts
1839        )
1840        return this

Append to or set the SELECT of the union recursively.

Example:
>>> from sqlglot import parse_one
>>> parse_one("select a from x union select a from y union select a from z").select("b").sql()
'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Union: the modified expression.

is_star: bool

Checks whether an expression is a star.

class Except(Union):
1863class Except(Union):
1864    pass
class Intersect(Union):
1867class Intersect(Union):
1868    pass
class Unnest(UDTF):
1871class Unnest(UDTF):
1872    arg_types = {
1873        "expressions": True,
1874        "ordinality": False,
1875        "alias": False,
1876        "offset": False,
1877    }
class Update(Expression):
1880class Update(Expression):
1881    arg_types = {
1882        "with": False,
1883        "this": False,
1884        "expressions": True,
1885        "from": False,
1886        "where": False,
1887    }
class Values(UDTF):
1890class Values(UDTF):
1891    arg_types = {
1892        "expressions": True,
1893        "ordinality": False,
1894        "alias": False,
1895    }
class Var(Expression):
1898class Var(Expression):
1899    pass
class Schema(Expression):
1902class Schema(Expression):
1903    arg_types = {"this": False, "expressions": False}
class Lock(Expression):
1908class Lock(Expression):
1909    arg_types = {"update": True}
class Select(Subqueryable):
1912class Select(Subqueryable):
1913    arg_types = {
1914        "with": False,
1915        "expressions": False,
1916        "hint": False,
1917        "distinct": False,
1918        "into": False,
1919        "from": False,
1920        **QUERY_MODIFIERS,
1921    }
1922
1923    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1924        """
1925        Set the FROM expression.
1926
1927        Example:
1928            >>> Select().from_("tbl").select("x").sql()
1929            'SELECT x FROM tbl'
1930
1931        Args:
1932            *expressions (str | Expression): the SQL code strings to parse.
1933                If a `From` instance is passed, this is used as-is.
1934                If another `Expression` instance is passed, it will be wrapped in a `From`.
1935            append (bool): if `True`, add to any existing expressions.
1936                Otherwise, this flattens all the `From` expression into a single expression.
1937            dialect (str): the dialect used to parse the input expression.
1938            copy (bool): if `False`, modify this expression instance in-place.
1939            opts (kwargs): other options to use to parse the input expressions.
1940
1941        Returns:
1942            Select: the modified expression.
1943        """
1944        return _apply_child_list_builder(
1945            *expressions,
1946            instance=self,
1947            arg="from",
1948            append=append,
1949            copy=copy,
1950            prefix="FROM",
1951            into=From,
1952            dialect=dialect,
1953            **opts,
1954        )
1955
1956    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1957        """
1958        Set the GROUP BY expression.
1959
1960        Example:
1961            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1962            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1963
1964        Args:
1965            *expressions (str | Expression): the SQL code strings to parse.
1966                If a `Group` instance is passed, this is used as-is.
1967                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1968                If nothing is passed in then a group by is not applied to the expression
1969            append (bool): if `True`, add to any existing expressions.
1970                Otherwise, this flattens all the `Group` expression into a single expression.
1971            dialect (str): the dialect used to parse the input expression.
1972            copy (bool): if `False`, modify this expression instance in-place.
1973            opts (kwargs): other options to use to parse the input expressions.
1974
1975        Returns:
1976            Select: the modified expression.
1977        """
1978        if not expressions:
1979            return self if not copy else self.copy()
1980        return _apply_child_list_builder(
1981            *expressions,
1982            instance=self,
1983            arg="group",
1984            append=append,
1985            copy=copy,
1986            prefix="GROUP BY",
1987            into=Group,
1988            dialect=dialect,
1989            **opts,
1990        )
1991
1992    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1993        """
1994        Set the ORDER BY expression.
1995
1996        Example:
1997            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1998            'SELECT x FROM tbl ORDER BY x DESC'
1999
2000        Args:
2001            *expressions (str | Expression): the SQL code strings to parse.
2002                If a `Group` instance is passed, this is used as-is.
2003                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2004            append (bool): if `True`, add to any existing expressions.
2005                Otherwise, this flattens all the `Order` expression into a single expression.
2006            dialect (str): the dialect used to parse the input expression.
2007            copy (bool): if `False`, modify this expression instance in-place.
2008            opts (kwargs): other options to use to parse the input expressions.
2009
2010        Returns:
2011            Select: the modified expression.
2012        """
2013        return _apply_child_list_builder(
2014            *expressions,
2015            instance=self,
2016            arg="order",
2017            append=append,
2018            copy=copy,
2019            prefix="ORDER BY",
2020            into=Order,
2021            dialect=dialect,
2022            **opts,
2023        )
2024
2025    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2026        """
2027        Set the SORT BY expression.
2028
2029        Example:
2030            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2031            'SELECT x FROM tbl SORT BY x DESC'
2032
2033        Args:
2034            *expressions (str | Expression): the SQL code strings to parse.
2035                If a `Group` instance is passed, this is used as-is.
2036                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2037            append (bool): if `True`, add to any existing expressions.
2038                Otherwise, this flattens all the `Order` expression into a single expression.
2039            dialect (str): the dialect used to parse the input expression.
2040            copy (bool): if `False`, modify this expression instance in-place.
2041            opts (kwargs): other options to use to parse the input expressions.
2042
2043        Returns:
2044            Select: the modified expression.
2045        """
2046        return _apply_child_list_builder(
2047            *expressions,
2048            instance=self,
2049            arg="sort",
2050            append=append,
2051            copy=copy,
2052            prefix="SORT BY",
2053            into=Sort,
2054            dialect=dialect,
2055            **opts,
2056        )
2057
2058    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2059        """
2060        Set the CLUSTER BY expression.
2061
2062        Example:
2063            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2064            'SELECT x FROM tbl CLUSTER BY x DESC'
2065
2066        Args:
2067            *expressions (str | Expression): the SQL code strings to parse.
2068                If a `Group` instance is passed, this is used as-is.
2069                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2070            append (bool): if `True`, add to any existing expressions.
2071                Otherwise, this flattens all the `Order` expression into a single expression.
2072            dialect (str): the dialect used to parse the input expression.
2073            copy (bool): if `False`, modify this expression instance in-place.
2074            opts (kwargs): other options to use to parse the input expressions.
2075
2076        Returns:
2077            Select: the modified expression.
2078        """
2079        return _apply_child_list_builder(
2080            *expressions,
2081            instance=self,
2082            arg="cluster",
2083            append=append,
2084            copy=copy,
2085            prefix="CLUSTER BY",
2086            into=Cluster,
2087            dialect=dialect,
2088            **opts,
2089        )
2090
2091    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2092        """
2093        Set the LIMIT expression.
2094
2095        Example:
2096            >>> Select().from_("tbl").select("x").limit(10).sql()
2097            'SELECT x FROM tbl LIMIT 10'
2098
2099        Args:
2100            expression (str | int | Expression): the SQL code string to parse.
2101                This can also be an integer.
2102                If a `Limit` instance is passed, this is used as-is.
2103                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2104            dialect (str): the dialect used to parse the input expression.
2105            copy (bool): if `False`, modify this expression instance in-place.
2106            opts (kwargs): other options to use to parse the input expressions.
2107
2108        Returns:
2109            Select: the modified expression.
2110        """
2111        return _apply_builder(
2112            expression=expression,
2113            instance=self,
2114            arg="limit",
2115            into=Limit,
2116            prefix="LIMIT",
2117            dialect=dialect,
2118            copy=copy,
2119            **opts,
2120        )
2121
2122    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2123        """
2124        Set the OFFSET expression.
2125
2126        Example:
2127            >>> Select().from_("tbl").select("x").offset(10).sql()
2128            'SELECT x FROM tbl OFFSET 10'
2129
2130        Args:
2131            expression (str | int | Expression): the SQL code string to parse.
2132                This can also be an integer.
2133                If a `Offset` instance is passed, this is used as-is.
2134                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2135            dialect (str): the dialect used to parse the input expression.
2136            copy (bool): if `False`, modify this expression instance in-place.
2137            opts (kwargs): other options to use to parse the input expressions.
2138
2139        Returns:
2140            Select: the modified expression.
2141        """
2142        return _apply_builder(
2143            expression=expression,
2144            instance=self,
2145            arg="offset",
2146            into=Offset,
2147            prefix="OFFSET",
2148            dialect=dialect,
2149            copy=copy,
2150            **opts,
2151        )
2152
2153    def select(
2154        self,
2155        *expressions: str | Expression,
2156        append: bool = True,
2157        dialect: DialectType = None,
2158        copy: bool = True,
2159        **opts,
2160    ) -> Select:
2161        """
2162        Append to or set the SELECT expressions.
2163
2164        Example:
2165            >>> Select().select("x", "y").sql()
2166            'SELECT x, y'
2167
2168        Args:
2169            *expressions: the SQL code strings to parse.
2170                If an `Expression` instance is passed, it will be used as-is.
2171            append: if `True`, add to any existing expressions.
2172                Otherwise, this resets the expressions.
2173            dialect: the dialect used to parse the input expressions.
2174            copy: if `False`, modify this expression instance in-place.
2175            opts: other options to use to parse the input expressions.
2176
2177        Returns:
2178            Select: the modified expression.
2179        """
2180        return _apply_list_builder(
2181            *expressions,
2182            instance=self,
2183            arg="expressions",
2184            append=append,
2185            dialect=dialect,
2186            copy=copy,
2187            **opts,
2188        )
2189
2190    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2191        """
2192        Append to or set the LATERAL expressions.
2193
2194        Example:
2195            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2196            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2197
2198        Args:
2199            *expressions (str | Expression): the SQL code strings to parse.
2200                If an `Expression` instance is passed, it will be used as-is.
2201            append (bool): if `True`, add to any existing expressions.
2202                Otherwise, this resets the expressions.
2203            dialect (str): the dialect used to parse the input expressions.
2204            copy (bool): if `False`, modify this expression instance in-place.
2205            opts (kwargs): other options to use to parse the input expressions.
2206
2207        Returns:
2208            Select: the modified expression.
2209        """
2210        return _apply_list_builder(
2211            *expressions,
2212            instance=self,
2213            arg="laterals",
2214            append=append,
2215            into=Lateral,
2216            prefix="LATERAL VIEW",
2217            dialect=dialect,
2218            copy=copy,
2219            **opts,
2220        )
2221
2222    def join(
2223        self,
2224        expression,
2225        on=None,
2226        using=None,
2227        append=True,
2228        join_type=None,
2229        join_alias=None,
2230        dialect=None,
2231        copy=True,
2232        **opts,
2233    ) -> Select:
2234        """
2235        Append to or set the JOIN expressions.
2236
2237        Example:
2238            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2239            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2240
2241            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2242            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2243
2244            Use `join_type` to change the type of join:
2245
2246            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2247            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2248
2249        Args:
2250            expression (str | Expression): the SQL code string to parse.
2251                If an `Expression` instance is passed, it will be used as-is.
2252            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2253                If an `Expression` instance is passed, it will be used as-is.
2254            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2255                If an `Expression` instance is passed, it will be used as-is.
2256            append (bool): if `True`, add to any existing expressions.
2257                Otherwise, this resets the expressions.
2258            join_type (str): If set, alter the parsed join type
2259            dialect (str): the dialect used to parse the input expressions.
2260            copy (bool): if `False`, modify this expression instance in-place.
2261            opts (kwargs): other options to use to parse the input expressions.
2262
2263        Returns:
2264            Select: the modified expression.
2265        """
2266        parse_args = {"dialect": dialect, **opts}
2267
2268        try:
2269            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2270        except ParseError:
2271            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2272
2273        join = expression if isinstance(expression, Join) else Join(this=expression)
2274
2275        if isinstance(join.this, Select):
2276            join.this.replace(join.this.subquery())
2277
2278        if join_type:
2279            natural: t.Optional[Token]
2280            side: t.Optional[Token]
2281            kind: t.Optional[Token]
2282
2283            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2284
2285            if natural:
2286                join.set("natural", True)
2287            if side:
2288                join.set("side", side.text)
2289            if kind:
2290                join.set("kind", kind.text)
2291
2292        if on:
2293            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2294            join.set("on", on)
2295
2296        if using:
2297            join = _apply_list_builder(
2298                *ensure_collection(using),
2299                instance=join,
2300                arg="using",
2301                append=append,
2302                copy=copy,
2303                **opts,
2304            )
2305
2306        if join_alias:
2307            join.set("this", alias_(join.this, join_alias, table=True))
2308        return _apply_list_builder(
2309            join,
2310            instance=self,
2311            arg="joins",
2312            append=append,
2313            copy=copy,
2314            **opts,
2315        )
2316
2317    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2318        """
2319        Append to or set the WHERE expressions.
2320
2321        Example:
2322            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2323            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2324
2325        Args:
2326            *expressions (str | Expression): the SQL code strings to parse.
2327                If an `Expression` instance is passed, it will be used as-is.
2328                Multiple expressions are combined with an AND operator.
2329            append (bool): if `True`, AND the new expressions to any existing expression.
2330                Otherwise, this resets the expression.
2331            dialect (str): the dialect used to parse the input expressions.
2332            copy (bool): if `False`, modify this expression instance in-place.
2333            opts (kwargs): other options to use to parse the input expressions.
2334
2335        Returns:
2336            Select: the modified expression.
2337        """
2338        return _apply_conjunction_builder(
2339            *expressions,
2340            instance=self,
2341            arg="where",
2342            append=append,
2343            into=Where,
2344            dialect=dialect,
2345            copy=copy,
2346            **opts,
2347        )
2348
2349    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2350        """
2351        Append to or set the HAVING expressions.
2352
2353        Example:
2354            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2355            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2356
2357        Args:
2358            *expressions (str | Expression): the SQL code strings to parse.
2359                If an `Expression` instance is passed, it will be used as-is.
2360                Multiple expressions are combined with an AND operator.
2361            append (bool): if `True`, AND the new expressions to any existing expression.
2362                Otherwise, this resets the expression.
2363            dialect (str): the dialect used to parse the input expressions.
2364            copy (bool): if `False`, modify this expression instance in-place.
2365            opts (kwargs): other options to use to parse the input expressions.
2366
2367        Returns:
2368            Select: the modified expression.
2369        """
2370        return _apply_conjunction_builder(
2371            *expressions,
2372            instance=self,
2373            arg="having",
2374            append=append,
2375            into=Having,
2376            dialect=dialect,
2377            copy=copy,
2378            **opts,
2379        )
2380
2381    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2382        return _apply_list_builder(
2383            *expressions,
2384            instance=self,
2385            arg="windows",
2386            append=append,
2387            into=Window,
2388            dialect=dialect,
2389            copy=copy,
2390            **opts,
2391        )
2392
2393    def distinct(self, distinct=True, copy=True) -> Select:
2394        """
2395        Set the OFFSET expression.
2396
2397        Example:
2398            >>> Select().from_("tbl").select("x").distinct().sql()
2399            'SELECT DISTINCT x FROM tbl'
2400
2401        Args:
2402            distinct (bool): whether the Select should be distinct
2403            copy (bool): if `False`, modify this expression instance in-place.
2404
2405        Returns:
2406            Select: the modified expression.
2407        """
2408        instance = _maybe_copy(self, copy)
2409        instance.set("distinct", Distinct() if distinct else None)
2410        return instance
2411
2412    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2413        """
2414        Convert this expression to a CREATE TABLE AS statement.
2415
2416        Example:
2417            >>> Select().select("*").from_("tbl").ctas("x").sql()
2418            'CREATE TABLE x AS SELECT * FROM tbl'
2419
2420        Args:
2421            table (str | Expression): the SQL code string to parse as the table name.
2422                If another `Expression` instance is passed, it will be used as-is.
2423            properties (dict): an optional mapping of table properties
2424            dialect (str): the dialect used to parse the input table.
2425            copy (bool): if `False`, modify this expression instance in-place.
2426            opts (kwargs): other options to use to parse the input table.
2427
2428        Returns:
2429            Create: the CREATE TABLE AS expression
2430        """
2431        instance = _maybe_copy(self, copy)
2432        table_expression = maybe_parse(
2433            table,
2434            into=Table,
2435            dialect=dialect,
2436            **opts,
2437        )
2438        properties_expression = None
2439        if properties:
2440            properties_expression = Properties.from_dict(properties)
2441
2442        return Create(
2443            this=table_expression,
2444            kind="table",
2445            expression=instance,
2446            properties=properties_expression,
2447        )
2448
2449    def lock(self, update: bool = True, copy: bool = True) -> Select:
2450        """
2451        Set the locking read mode for this expression.
2452
2453        Examples:
2454            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2455            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2456
2457            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2458            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2459
2460        Args:
2461            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2462            copy: if `False`, modify this expression instance in-place.
2463
2464        Returns:
2465            The modified expression.
2466        """
2467
2468        inst = _maybe_copy(self, copy)
2469        inst.set("lock", Lock(update=update))
2470
2471        return inst
2472
2473    @property
2474    def named_selects(self) -> t.List[str]:
2475        return [e.output_name for e in self.expressions if e.alias_or_name]
2476
2477    @property
2478    def is_star(self) -> bool:
2479        return any(expression.is_star for expression in self.expressions)
2480
2481    @property
2482    def selects(self) -> t.List[Expression]:
2483        return self.expressions
def from_( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1923    def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1924        """
1925        Set the FROM expression.
1926
1927        Example:
1928            >>> Select().from_("tbl").select("x").sql()
1929            'SELECT x FROM tbl'
1930
1931        Args:
1932            *expressions (str | Expression): the SQL code strings to parse.
1933                If a `From` instance is passed, this is used as-is.
1934                If another `Expression` instance is passed, it will be wrapped in a `From`.
1935            append (bool): if `True`, add to any existing expressions.
1936                Otherwise, this flattens all the `From` expression into a single expression.
1937            dialect (str): the dialect used to parse the input expression.
1938            copy (bool): if `False`, modify this expression instance in-place.
1939            opts (kwargs): other options to use to parse the input expressions.
1940
1941        Returns:
1942            Select: the modified expression.
1943        """
1944        return _apply_child_list_builder(
1945            *expressions,
1946            instance=self,
1947            arg="from",
1948            append=append,
1949            copy=copy,
1950            prefix="FROM",
1951            into=From,
1952            dialect=dialect,
1953            **opts,
1954        )

Set the FROM expression.

Example:
>>> Select().from_("tbl").select("x").sql()
'SELECT x FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a From instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a From.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the From expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def group_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1956    def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1957        """
1958        Set the GROUP BY expression.
1959
1960        Example:
1961            >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
1962            'SELECT x, COUNT(1) FROM tbl GROUP BY x'
1963
1964        Args:
1965            *expressions (str | Expression): the SQL code strings to parse.
1966                If a `Group` instance is passed, this is used as-is.
1967                If another `Expression` instance is passed, it will be wrapped in a `Group`.
1968                If nothing is passed in then a group by is not applied to the expression
1969            append (bool): if `True`, add to any existing expressions.
1970                Otherwise, this flattens all the `Group` expression into a single expression.
1971            dialect (str): the dialect used to parse the input expression.
1972            copy (bool): if `False`, modify this expression instance in-place.
1973            opts (kwargs): other options to use to parse the input expressions.
1974
1975        Returns:
1976            Select: the modified expression.
1977        """
1978        if not expressions:
1979            return self if not copy else self.copy()
1980        return _apply_child_list_builder(
1981            *expressions,
1982            instance=self,
1983            arg="group",
1984            append=append,
1985            copy=copy,
1986            prefix="GROUP BY",
1987            into=Group,
1988            dialect=dialect,
1989            **opts,
1990        )

Set the GROUP BY expression.

Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql()
'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Group. If nothing is passed in then a group by is not applied to the expression
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Group expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def order_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1992    def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
1993        """
1994        Set the ORDER BY expression.
1995
1996        Example:
1997            >>> Select().from_("tbl").select("x").order_by("x DESC").sql()
1998            'SELECT x FROM tbl ORDER BY x DESC'
1999
2000        Args:
2001            *expressions (str | Expression): the SQL code strings to parse.
2002                If a `Group` instance is passed, this is used as-is.
2003                If another `Expression` instance is passed, it will be wrapped in a `Order`.
2004            append (bool): if `True`, add to any existing expressions.
2005                Otherwise, this flattens all the `Order` expression into a single expression.
2006            dialect (str): the dialect used to parse the input expression.
2007            copy (bool): if `False`, modify this expression instance in-place.
2008            opts (kwargs): other options to use to parse the input expressions.
2009
2010        Returns:
2011            Select: the modified expression.
2012        """
2013        return _apply_child_list_builder(
2014            *expressions,
2015            instance=self,
2016            arg="order",
2017            append=append,
2018            copy=copy,
2019            prefix="ORDER BY",
2020            into=Order,
2021            dialect=dialect,
2022            **opts,
2023        )

Set the ORDER BY expression.

Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql()
'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Order.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def sort_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2025    def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2026        """
2027        Set the SORT BY expression.
2028
2029        Example:
2030            >>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
2031            'SELECT x FROM tbl SORT BY x DESC'
2032
2033        Args:
2034            *expressions (str | Expression): the SQL code strings to parse.
2035                If a `Group` instance is passed, this is used as-is.
2036                If another `Expression` instance is passed, it will be wrapped in a `SORT`.
2037            append (bool): if `True`, add to any existing expressions.
2038                Otherwise, this flattens all the `Order` expression into a single expression.
2039            dialect (str): the dialect used to parse the input expression.
2040            copy (bool): if `False`, modify this expression instance in-place.
2041            opts (kwargs): other options to use to parse the input expressions.
2042
2043        Returns:
2044            Select: the modified expression.
2045        """
2046        return _apply_child_list_builder(
2047            *expressions,
2048            instance=self,
2049            arg="sort",
2050            append=append,
2051            copy=copy,
2052            prefix="SORT BY",
2053            into=Sort,
2054            dialect=dialect,
2055            **opts,
2056        )

Set the SORT BY expression.

Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql()
'SELECT x FROM tbl SORT BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a SORT.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def cluster_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2058    def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2059        """
2060        Set the CLUSTER BY expression.
2061
2062        Example:
2063            >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
2064            'SELECT x FROM tbl CLUSTER BY x DESC'
2065
2066        Args:
2067            *expressions (str | Expression): the SQL code strings to parse.
2068                If a `Group` instance is passed, this is used as-is.
2069                If another `Expression` instance is passed, it will be wrapped in a `Cluster`.
2070            append (bool): if `True`, add to any existing expressions.
2071                Otherwise, this flattens all the `Order` expression into a single expression.
2072            dialect (str): the dialect used to parse the input expression.
2073            copy (bool): if `False`, modify this expression instance in-place.
2074            opts (kwargs): other options to use to parse the input expressions.
2075
2076        Returns:
2077            Select: the modified expression.
2078        """
2079        return _apply_child_list_builder(
2080            *expressions,
2081            instance=self,
2082            arg="cluster",
2083            append=append,
2084            copy=copy,
2085            prefix="CLUSTER BY",
2086            into=Cluster,
2087            dialect=dialect,
2088            **opts,
2089        )

Set the CLUSTER BY expression.

Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql()
'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If a Group instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Cluster.
  • append (bool): if True, add to any existing expressions. Otherwise, this flattens all the Order expression into a single expression.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def limit( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2091    def limit(self, expression, dialect=None, copy=True, **opts) -> Select:
2092        """
2093        Set the LIMIT expression.
2094
2095        Example:
2096            >>> Select().from_("tbl").select("x").limit(10).sql()
2097            'SELECT x FROM tbl LIMIT 10'
2098
2099        Args:
2100            expression (str | int | Expression): the SQL code string to parse.
2101                This can also be an integer.
2102                If a `Limit` instance is passed, this is used as-is.
2103                If another `Expression` instance is passed, it will be wrapped in a `Limit`.
2104            dialect (str): the dialect used to parse the input expression.
2105            copy (bool): if `False`, modify this expression instance in-place.
2106            opts (kwargs): other options to use to parse the input expressions.
2107
2108        Returns:
2109            Select: the modified expression.
2110        """
2111        return _apply_builder(
2112            expression=expression,
2113            instance=self,
2114            arg="limit",
2115            into=Limit,
2116            prefix="LIMIT",
2117            dialect=dialect,
2118            copy=copy,
2119            **opts,
2120        )

Set the LIMIT expression.

Example:
>>> Select().from_("tbl").select("x").limit(10).sql()
'SELECT x FROM tbl LIMIT 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Limit instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Limit.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def offset( self, expression, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2122    def offset(self, expression, dialect=None, copy=True, **opts) -> Select:
2123        """
2124        Set the OFFSET expression.
2125
2126        Example:
2127            >>> Select().from_("tbl").select("x").offset(10).sql()
2128            'SELECT x FROM tbl OFFSET 10'
2129
2130        Args:
2131            expression (str | int | Expression): the SQL code string to parse.
2132                This can also be an integer.
2133                If a `Offset` instance is passed, this is used as-is.
2134                If another `Expression` instance is passed, it will be wrapped in a `Offset`.
2135            dialect (str): the dialect used to parse the input expression.
2136            copy (bool): if `False`, modify this expression instance in-place.
2137            opts (kwargs): other options to use to parse the input expressions.
2138
2139        Returns:
2140            Select: the modified expression.
2141        """
2142        return _apply_builder(
2143            expression=expression,
2144            instance=self,
2145            arg="offset",
2146            into=Offset,
2147            prefix="OFFSET",
2148            dialect=dialect,
2149            copy=copy,
2150            **opts,
2151        )

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").offset(10).sql()
'SELECT x FROM tbl OFFSET 10'
Arguments:
  • expression (str | int | Expression): the SQL code string to parse. This can also be an integer. If a Offset instance is passed, this is used as-is. If another Expression instance is passed, it will be wrapped in a Offset.
  • dialect (str): the dialect used to parse the input expression.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Select:
2153    def select(
2154        self,
2155        *expressions: str | Expression,
2156        append: bool = True,
2157        dialect: DialectType = None,
2158        copy: bool = True,
2159        **opts,
2160    ) -> Select:
2161        """
2162        Append to or set the SELECT expressions.
2163
2164        Example:
2165            >>> Select().select("x", "y").sql()
2166            'SELECT x, y'
2167
2168        Args:
2169            *expressions: the SQL code strings to parse.
2170                If an `Expression` instance is passed, it will be used as-is.
2171            append: if `True`, add to any existing expressions.
2172                Otherwise, this resets the expressions.
2173            dialect: the dialect used to parse the input expressions.
2174            copy: if `False`, modify this expression instance in-place.
2175            opts: other options to use to parse the input expressions.
2176
2177        Returns:
2178            Select: the modified expression.
2179        """
2180        return _apply_list_builder(
2181            *expressions,
2182            instance=self,
2183            arg="expressions",
2184            append=append,
2185            dialect=dialect,
2186            copy=copy,
2187            **opts,
2188        )

Append to or set the SELECT expressions.

Example:
>>> Select().select("x", "y").sql()
'SELECT x, y'
Arguments:
  • *expressions: the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append: if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect: the dialect used to parse the input expressions.
  • copy: if False, modify this expression instance in-place.
  • opts: other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def lateral( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2190    def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2191        """
2192        Append to or set the LATERAL expressions.
2193
2194        Example:
2195            >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
2196            'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
2197
2198        Args:
2199            *expressions (str | Expression): the SQL code strings to parse.
2200                If an `Expression` instance is passed, it will be used as-is.
2201            append (bool): if `True`, add to any existing expressions.
2202                Otherwise, this resets the expressions.
2203            dialect (str): the dialect used to parse the input expressions.
2204            copy (bool): if `False`, modify this expression instance in-place.
2205            opts (kwargs): other options to use to parse the input expressions.
2206
2207        Returns:
2208            Select: the modified expression.
2209        """
2210        return _apply_list_builder(
2211            *expressions,
2212            instance=self,
2213            arg="laterals",
2214            append=append,
2215            into=Lateral,
2216            prefix="LATERAL VIEW",
2217            dialect=dialect,
2218            copy=copy,
2219            **opts,
2220        )

Append to or set the LATERAL expressions.

Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql()
'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def join( self, expression, on=None, using=None, append=True, join_type=None, join_alias=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2222    def join(
2223        self,
2224        expression,
2225        on=None,
2226        using=None,
2227        append=True,
2228        join_type=None,
2229        join_alias=None,
2230        dialect=None,
2231        copy=True,
2232        **opts,
2233    ) -> Select:
2234        """
2235        Append to or set the JOIN expressions.
2236
2237        Example:
2238            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
2239            'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
2240
2241            >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
2242            'SELECT 1 FROM a JOIN b USING (x, y, z)'
2243
2244            Use `join_type` to change the type of join:
2245
2246            >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
2247            'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
2248
2249        Args:
2250            expression (str | Expression): the SQL code string to parse.
2251                If an `Expression` instance is passed, it will be used as-is.
2252            on (str | Expression): optionally specify the join "on" criteria as a SQL string.
2253                If an `Expression` instance is passed, it will be used as-is.
2254            using (str | Expression): optionally specify the join "using" criteria as a SQL string.
2255                If an `Expression` instance is passed, it will be used as-is.
2256            append (bool): if `True`, add to any existing expressions.
2257                Otherwise, this resets the expressions.
2258            join_type (str): If set, alter the parsed join type
2259            dialect (str): the dialect used to parse the input expressions.
2260            copy (bool): if `False`, modify this expression instance in-place.
2261            opts (kwargs): other options to use to parse the input expressions.
2262
2263        Returns:
2264            Select: the modified expression.
2265        """
2266        parse_args = {"dialect": dialect, **opts}
2267
2268        try:
2269            expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args)
2270        except ParseError:
2271            expression = maybe_parse(expression, into=(Join, Expression), **parse_args)
2272
2273        join = expression if isinstance(expression, Join) else Join(this=expression)
2274
2275        if isinstance(join.this, Select):
2276            join.this.replace(join.this.subquery())
2277
2278        if join_type:
2279            natural: t.Optional[Token]
2280            side: t.Optional[Token]
2281            kind: t.Optional[Token]
2282
2283            natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args)  # type: ignore
2284
2285            if natural:
2286                join.set("natural", True)
2287            if side:
2288                join.set("side", side.text)
2289            if kind:
2290                join.set("kind", kind.text)
2291
2292        if on:
2293            on = and_(*ensure_collection(on), dialect=dialect, **opts)
2294            join.set("on", on)
2295
2296        if using:
2297            join = _apply_list_builder(
2298                *ensure_collection(using),
2299                instance=join,
2300                arg="using",
2301                append=append,
2302                copy=copy,
2303                **opts,
2304            )
2305
2306        if join_alias:
2307            join.set("this", alias_(join.this, join_alias, table=True))
2308        return _apply_list_builder(
2309            join,
2310            instance=self,
2311            arg="joins",
2312            append=append,
2313            copy=copy,
2314            **opts,
2315        )

Append to or set the JOIN expressions.

Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql()
'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'
>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql()
'SELECT 1 FROM a JOIN b USING (x, y, z)'

Use join_type to change the type of join:

>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql()
'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
  • expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, it will be used as-is.
  • on (str | Expression): optionally specify the join "on" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • using (str | Expression): optionally specify the join "using" criteria as a SQL string. If an Expression instance is passed, it will be used as-is.
  • append (bool): if True, add to any existing expressions. Otherwise, this resets the expressions.
  • join_type (str): If set, alter the parsed join type
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def where( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2317    def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2318        """
2319        Append to or set the WHERE expressions.
2320
2321        Example:
2322            >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
2323            "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
2324
2325        Args:
2326            *expressions (str | Expression): the SQL code strings to parse.
2327                If an `Expression` instance is passed, it will be used as-is.
2328                Multiple expressions are combined with an AND operator.
2329            append (bool): if `True`, AND the new expressions to any existing expression.
2330                Otherwise, this resets the expression.
2331            dialect (str): the dialect used to parse the input expressions.
2332            copy (bool): if `False`, modify this expression instance in-place.
2333            opts (kwargs): other options to use to parse the input expressions.
2334
2335        Returns:
2336            Select: the modified expression.
2337        """
2338        return _apply_conjunction_builder(
2339            *expressions,
2340            instance=self,
2341            arg="where",
2342            append=append,
2343            into=Where,
2344            dialect=dialect,
2345            copy=copy,
2346            **opts,
2347        )

Append to or set the WHERE expressions.

Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql()
"SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def having( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2349    def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2350        """
2351        Append to or set the HAVING expressions.
2352
2353        Example:
2354            >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
2355            'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
2356
2357        Args:
2358            *expressions (str | Expression): the SQL code strings to parse.
2359                If an `Expression` instance is passed, it will be used as-is.
2360                Multiple expressions are combined with an AND operator.
2361            append (bool): if `True`, AND the new expressions to any existing expression.
2362                Otherwise, this resets the expression.
2363            dialect (str): the dialect used to parse the input expressions.
2364            copy (bool): if `False`, modify this expression instance in-place.
2365            opts (kwargs): other options to use to parse the input expressions.
2366
2367        Returns:
2368            Select: the modified expression.
2369        """
2370        return _apply_conjunction_builder(
2371            *expressions,
2372            instance=self,
2373            arg="having",
2374            append=append,
2375            into=Having,
2376            dialect=dialect,
2377            copy=copy,
2378            **opts,
2379        )

Append to or set the HAVING expressions.

Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql()
'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, it will be used as-is. Multiple expressions are combined with an AND operator.
  • append (bool): if True, AND the new expressions to any existing expression. Otherwise, this resets the expression.
  • dialect (str): the dialect used to parse the input expressions.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Select: the modified expression.

def window( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2381    def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select:
2382        return _apply_list_builder(
2383            *expressions,
2384            instance=self,
2385            arg="windows",
2386            append=append,
2387            into=Window,
2388            dialect=dialect,
2389            copy=copy,
2390            **opts,
2391        )
def distinct(self, distinct=True, copy=True) -> sqlglot.expressions.Select:
2393    def distinct(self, distinct=True, copy=True) -> Select:
2394        """
2395        Set the OFFSET expression.
2396
2397        Example:
2398            >>> Select().from_("tbl").select("x").distinct().sql()
2399            'SELECT DISTINCT x FROM tbl'
2400
2401        Args:
2402            distinct (bool): whether the Select should be distinct
2403            copy (bool): if `False`, modify this expression instance in-place.
2404
2405        Returns:
2406            Select: the modified expression.
2407        """
2408        instance = _maybe_copy(self, copy)
2409        instance.set("distinct", Distinct() if distinct else None)
2410        return instance

Set the OFFSET expression.

Example:
>>> Select().from_("tbl").select("x").distinct().sql()
'SELECT DISTINCT x FROM tbl'
Arguments:
  • distinct (bool): whether the Select should be distinct
  • copy (bool): if False, modify this expression instance in-place.
Returns:

Select: the modified expression.

def ctas( self, table, properties=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Create:
2412    def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create:
2413        """
2414        Convert this expression to a CREATE TABLE AS statement.
2415
2416        Example:
2417            >>> Select().select("*").from_("tbl").ctas("x").sql()
2418            'CREATE TABLE x AS SELECT * FROM tbl'
2419
2420        Args:
2421            table (str | Expression): the SQL code string to parse as the table name.
2422                If another `Expression` instance is passed, it will be used as-is.
2423            properties (dict): an optional mapping of table properties
2424            dialect (str): the dialect used to parse the input table.
2425            copy (bool): if `False`, modify this expression instance in-place.
2426            opts (kwargs): other options to use to parse the input table.
2427
2428        Returns:
2429            Create: the CREATE TABLE AS expression
2430        """
2431        instance = _maybe_copy(self, copy)
2432        table_expression = maybe_parse(
2433            table,
2434            into=Table,
2435            dialect=dialect,
2436            **opts,
2437        )
2438        properties_expression = None
2439        if properties:
2440            properties_expression = Properties.from_dict(properties)
2441
2442        return Create(
2443            this=table_expression,
2444            kind="table",
2445            expression=instance,
2446            properties=properties_expression,
2447        )

Convert this expression to a CREATE TABLE AS statement.

Example:
>>> Select().select("*").from_("tbl").ctas("x").sql()
'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
  • table (str | Expression): the SQL code string to parse as the table name. If another Expression instance is passed, it will be used as-is.
  • properties (dict): an optional mapping of table properties
  • dialect (str): the dialect used to parse the input table.
  • copy (bool): if False, modify this expression instance in-place.
  • opts (kwargs): other options to use to parse the input table.
Returns:

Create: the CREATE TABLE AS expression

def lock( self, update: bool = True, copy: bool = True) -> sqlglot.expressions.Select:
2449    def lock(self, update: bool = True, copy: bool = True) -> Select:
2450        """
2451        Set the locking read mode for this expression.
2452
2453        Examples:
2454            >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
2455            "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
2456
2457            >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
2458            "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
2459
2460        Args:
2461            update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`.
2462            copy: if `False`, modify this expression instance in-place.
2463
2464        Returns:
2465            The modified expression.
2466        """
2467
2468        inst = _maybe_copy(self, copy)
2469        inst.set("lock", Lock(update=update))
2470
2471        return inst

Set the locking read mode for this expression.

Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR UPDATE"
>>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql")
"SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
  • update: if True, the locking type will be FOR UPDATE, else it will be FOR SHARE.
  • copy: if False, modify this expression instance in-place.
Returns:

The modified expression.

is_star: bool

Checks whether an expression is a star.

class Subquery(DerivedTable, Unionable):
2486class Subquery(DerivedTable, Unionable):
2487    arg_types = {
2488        "this": True,
2489        "alias": False,
2490        "with": False,
2491        **QUERY_MODIFIERS,
2492    }
2493
2494    def unnest(self):
2495        """
2496        Returns the first non subquery.
2497        """
2498        expression = self
2499        while isinstance(expression, Subquery):
2500            expression = expression.this
2501        return expression
2502
2503    @property
2504    def is_star(self) -> bool:
2505        return self.this.is_star
2506
2507    @property
2508    def output_name(self):
2509        return self.alias
def unnest(self):
2494    def unnest(self):
2495        """
2496        Returns the first non subquery.
2497        """
2498        expression = self
2499        while isinstance(expression, Subquery):
2500            expression = expression.this
2501        return expression

Returns the first non subquery.

is_star: bool

Checks whether an expression is a star.

output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class TableSample(Expression):
2512class TableSample(Expression):
2513    arg_types = {
2514        "this": False,
2515        "method": False,
2516        "bucket_numerator": False,
2517        "bucket_denominator": False,
2518        "bucket_field": False,
2519        "percent": False,
2520        "rows": False,
2521        "size": False,
2522        "seed": False,
2523    }
class Tag(Expression):
2526class Tag(Expression):
2527    """Tags are used for generating arbitrary sql like SELECT <span>x</span>."""
2528
2529    arg_types = {
2530        "this": False,
2531        "prefix": False,
2532        "postfix": False,
2533    }

Tags are used for generating arbitrary sql like SELECT x.

class Pivot(Expression):
2536class Pivot(Expression):
2537    arg_types = {
2538        "this": False,
2539        "alias": False,
2540        "expressions": True,
2541        "field": True,
2542        "unpivot": True,
2543    }
class Window(Expression):
2546class Window(Expression):
2547    arg_types = {
2548        "this": True,
2549        "partition_by": False,
2550        "order": False,
2551        "spec": False,
2552        "alias": False,
2553    }
class WindowSpec(Expression):
2556class WindowSpec(Expression):
2557    arg_types = {
2558        "kind": False,
2559        "start": False,
2560        "start_side": False,
2561        "end": False,
2562        "end_side": False,
2563    }
class Where(Expression):
2566class Where(Expression):
2567    pass
class Star(Expression):
2570class Star(Expression):
2571    arg_types = {"except": False, "replace": False}
2572
2573    @property
2574    def name(self) -> str:
2575        return "*"
2576
2577    @property
2578    def output_name(self):
2579        return self.name
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Parameter(Expression):
2582class Parameter(Expression):
2583    arg_types = {"this": True, "wrapped": False}
class SessionParameter(Expression):
2586class SessionParameter(Expression):
2587    arg_types = {"this": True, "kind": False}
class Placeholder(Expression):
2590class Placeholder(Expression):
2591    arg_types = {"this": False}
class Null(Condition):
2594class Null(Condition):
2595    arg_types: t.Dict[str, t.Any] = {}
2596
2597    @property
2598    def name(self) -> str:
2599        return "NULL"
class Boolean(Condition):
2602class Boolean(Condition):
2603    pass
class DataType(Expression):
2606class DataType(Expression):
2607    arg_types = {
2608        "this": True,
2609        "expressions": False,
2610        "nested": False,
2611        "values": False,
2612        "prefix": False,
2613    }
2614
2615    class Type(AutoName):
2616        CHAR = auto()
2617        NCHAR = auto()
2618        VARCHAR = auto()
2619        NVARCHAR = auto()
2620        TEXT = auto()
2621        MEDIUMTEXT = auto()
2622        LONGTEXT = auto()
2623        MEDIUMBLOB = auto()
2624        LONGBLOB = auto()
2625        BINARY = auto()
2626        VARBINARY = auto()
2627        INT = auto()
2628        TINYINT = auto()
2629        SMALLINT = auto()
2630        BIGINT = auto()
2631        FLOAT = auto()
2632        DOUBLE = auto()
2633        DECIMAL = auto()
2634        BOOLEAN = auto()
2635        JSON = auto()
2636        JSONB = auto()
2637        INTERVAL = auto()
2638        TIME = auto()
2639        TIMESTAMP = auto()
2640        TIMESTAMPTZ = auto()
2641        TIMESTAMPLTZ = auto()
2642        DATE = auto()
2643        DATETIME = auto()
2644        ARRAY = auto()
2645        MAP = auto()
2646        UUID = auto()
2647        GEOGRAPHY = auto()
2648        GEOMETRY = auto()
2649        STRUCT = auto()
2650        NULLABLE = auto()
2651        HLLSKETCH = auto()
2652        HSTORE = auto()
2653        SUPER = auto()
2654        SERIAL = auto()
2655        SMALLSERIAL = auto()
2656        BIGSERIAL = auto()
2657        XML = auto()
2658        UNIQUEIDENTIFIER = auto()
2659        MONEY = auto()
2660        SMALLMONEY = auto()
2661        ROWVERSION = auto()
2662        IMAGE = auto()
2663        VARIANT = auto()
2664        OBJECT = auto()
2665        INET = auto()
2666        NULL = auto()
2667        UNKNOWN = auto()  # Sentinel value, useful for type annotation
2668
2669    TEXT_TYPES = {
2670        Type.CHAR,
2671        Type.NCHAR,
2672        Type.VARCHAR,
2673        Type.NVARCHAR,
2674        Type.TEXT,
2675    }
2676
2677    INTEGER_TYPES = {
2678        Type.INT,
2679        Type.TINYINT,
2680        Type.SMALLINT,
2681        Type.BIGINT,
2682    }
2683
2684    FLOAT_TYPES = {
2685        Type.FLOAT,
2686        Type.DOUBLE,
2687    }
2688
2689    NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES}
2690
2691    TEMPORAL_TYPES = {
2692        Type.TIMESTAMP,
2693        Type.TIMESTAMPTZ,
2694        Type.TIMESTAMPLTZ,
2695        Type.DATE,
2696        Type.DATETIME,
2697    }
2698
2699    @classmethod
2700    def build(
2701        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2702    ) -> DataType:
2703        from sqlglot import parse_one
2704
2705        if isinstance(dtype, str):
2706            if dtype.upper() in cls.Type.__members__:
2707                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2708            else:
2709                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2710            if data_type_exp is None:
2711                raise ValueError(f"Unparsable data type value: {dtype}")
2712        elif isinstance(dtype, DataType.Type):
2713            data_type_exp = DataType(this=dtype)
2714        elif isinstance(dtype, DataType):
2715            return dtype
2716        else:
2717            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2718        return DataType(**{**data_type_exp.args, **kwargs})
2719
2720    def is_type(self, dtype: DataType.Type) -> bool:
2721        return self.this == dtype
@classmethod
def build( cls, dtype: str | sqlglot.expressions.DataType | sqlglot.expressions.DataType.Type, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.DataType:
2699    @classmethod
2700    def build(
2701        cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs
2702    ) -> DataType:
2703        from sqlglot import parse_one
2704
2705        if isinstance(dtype, str):
2706            if dtype.upper() in cls.Type.__members__:
2707                data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()])
2708            else:
2709                data_type_exp = parse_one(dtype, read=dialect, into=DataType)
2710            if data_type_exp is None:
2711                raise ValueError(f"Unparsable data type value: {dtype}")
2712        elif isinstance(dtype, DataType.Type):
2713            data_type_exp = DataType(this=dtype)
2714        elif isinstance(dtype, DataType):
2715            return dtype
2716        else:
2717            raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type")
2718        return DataType(**{**data_type_exp.args, **kwargs})
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
2720    def is_type(self, dtype: DataType.Type) -> bool:
2721        return self.this == dtype
class DataType.Type(sqlglot.helper.AutoName):
2615    class Type(AutoName):
2616        CHAR = auto()
2617        NCHAR = auto()
2618        VARCHAR = auto()
2619        NVARCHAR = auto()
2620        TEXT = auto()
2621        MEDIUMTEXT = auto()
2622        LONGTEXT = auto()
2623        MEDIUMBLOB = auto()
2624        LONGBLOB = auto()
2625        BINARY = auto()
2626        VARBINARY = auto()
2627        INT = auto()
2628        TINYINT = auto()
2629        SMALLINT = auto()
2630        BIGINT = auto()
2631        FLOAT = auto()
2632        DOUBLE = auto()
2633        DECIMAL = auto()
2634        BOOLEAN = auto()
2635        JSON = auto()
2636        JSONB = auto()
2637        INTERVAL = auto()
2638        TIME = auto()
2639        TIMESTAMP = auto()
2640        TIMESTAMPTZ = auto()
2641        TIMESTAMPLTZ = auto()
2642        DATE = auto()
2643        DATETIME = auto()
2644        ARRAY = auto()
2645        MAP = auto()
2646        UUID = auto()
2647        GEOGRAPHY = auto()
2648        GEOMETRY = auto()
2649        STRUCT = auto()
2650        NULLABLE = auto()
2651        HLLSKETCH = auto()
2652        HSTORE = auto()
2653        SUPER = auto()
2654        SERIAL = auto()
2655        SMALLSERIAL = auto()
2656        BIGSERIAL = auto()
2657        XML = auto()
2658        UNIQUEIDENTIFIER = auto()
2659        MONEY = auto()
2660        SMALLMONEY = auto()
2661        ROWVERSION = auto()
2662        IMAGE = auto()
2663        VARIANT = auto()
2664        OBJECT = auto()
2665        INET = auto()
2666        NULL = auto()
2667        UNKNOWN = auto()  # Sentinel value, useful for type annotation

An enumeration.

CHAR = <Type.CHAR: 'CHAR'>
NCHAR = <Type.NCHAR: 'NCHAR'>
VARCHAR = <Type.VARCHAR: 'VARCHAR'>
NVARCHAR = <Type.NVARCHAR: 'NVARCHAR'>
TEXT = <Type.TEXT: 'TEXT'>
MEDIUMTEXT = <Type.MEDIUMTEXT: 'MEDIUMTEXT'>
LONGTEXT = <Type.LONGTEXT: 'LONGTEXT'>
MEDIUMBLOB = <Type.MEDIUMBLOB: 'MEDIUMBLOB'>
LONGBLOB = <Type.LONGBLOB: 'LONGBLOB'>
BINARY = <Type.BINARY: 'BINARY'>
VARBINARY = <Type.VARBINARY: 'VARBINARY'>
INT = <Type.INT: 'INT'>
TINYINT = <Type.TINYINT: 'TINYINT'>
SMALLINT = <Type.SMALLINT: 'SMALLINT'>
BIGINT = <Type.BIGINT: 'BIGINT'>
FLOAT = <Type.FLOAT: 'FLOAT'>
DOUBLE = <Type.DOUBLE: 'DOUBLE'>
DECIMAL = <Type.DECIMAL: 'DECIMAL'>
BOOLEAN = <Type.BOOLEAN: 'BOOLEAN'>
JSON = <Type.JSON: 'JSON'>
JSONB = <Type.JSONB: 'JSONB'>
INTERVAL = <Type.INTERVAL: 'INTERVAL'>
TIME = <Type.TIME: 'TIME'>
TIMESTAMP = <Type.TIMESTAMP: 'TIMESTAMP'>
TIMESTAMPTZ = <Type.TIMESTAMPTZ: 'TIMESTAMPTZ'>
TIMESTAMPLTZ = <Type.TIMESTAMPLTZ: 'TIMESTAMPLTZ'>
DATE = <Type.DATE: 'DATE'>
DATETIME = <Type.DATETIME: 'DATETIME'>
ARRAY = <Type.ARRAY: 'ARRAY'>
MAP = <Type.MAP: 'MAP'>
UUID = <Type.UUID: 'UUID'>
GEOGRAPHY = <Type.GEOGRAPHY: 'GEOGRAPHY'>
GEOMETRY = <Type.GEOMETRY: 'GEOMETRY'>
STRUCT = <Type.STRUCT: 'STRUCT'>
NULLABLE = <Type.NULLABLE: 'NULLABLE'>
HLLSKETCH = <Type.HLLSKETCH: 'HLLSKETCH'>
HSTORE = <Type.HSTORE: 'HSTORE'>
SUPER = <Type.SUPER: 'SUPER'>
SERIAL = <Type.SERIAL: 'SERIAL'>
SMALLSERIAL = <Type.SMALLSERIAL: 'SMALLSERIAL'>
BIGSERIAL = <Type.BIGSERIAL: 'BIGSERIAL'>
XML = <Type.XML: 'XML'>
UNIQUEIDENTIFIER = <Type.UNIQUEIDENTIFIER: 'UNIQUEIDENTIFIER'>
MONEY = <Type.MONEY: 'MONEY'>
SMALLMONEY = <Type.SMALLMONEY: 'SMALLMONEY'>
ROWVERSION = <Type.ROWVERSION: 'ROWVERSION'>
IMAGE = <Type.IMAGE: 'IMAGE'>
VARIANT = <Type.VARIANT: 'VARIANT'>
OBJECT = <Type.OBJECT: 'OBJECT'>
INET = <Type.INET: 'INET'>
NULL = <Type.NULL: 'NULL'>
UNKNOWN = <Type.UNKNOWN: 'UNKNOWN'>
Inherited Members
enum.Enum
name
value
class PseudoType(Expression):
2725class PseudoType(Expression):
2726    pass
class StructKwarg(Expression):
2729class StructKwarg(Expression):
2730    arg_types = {"this": True, "expression": True}
class SubqueryPredicate(Predicate):
2734class SubqueryPredicate(Predicate):
2735    pass
class All(SubqueryPredicate):
2738class All(SubqueryPredicate):
2739    pass
class Any(SubqueryPredicate):
2742class Any(SubqueryPredicate):
2743    pass
class Exists(SubqueryPredicate):
2746class Exists(SubqueryPredicate):
2747    pass
class Command(Expression):
2752class Command(Expression):
2753    arg_types = {"this": True, "expression": False}
class Transaction(Expression):
2756class Transaction(Expression):
2757    arg_types = {"this": False, "modes": False}
class Commit(Expression):
2760class Commit(Expression):
2761    arg_types = {"chain": False}
class Rollback(Expression):
2764class Rollback(Expression):
2765    arg_types = {"savepoint": False}
class AlterTable(Expression):
2768class AlterTable(Expression):
2769    arg_types = {"this": True, "actions": True, "exists": False}
class AddConstraint(Expression):
2772class AddConstraint(Expression):
2773    arg_types = {"this": False, "expression": False, "enforced": False}
class DropPartition(Expression):
2776class DropPartition(Expression):
2777    arg_types = {"expressions": True, "exists": False}
class Binary(Expression):
2781class Binary(Expression):
2782    arg_types = {"this": True, "expression": True}
2783
2784    @property
2785    def left(self):
2786        return self.this
2787
2788    @property
2789    def right(self):
2790        return self.expression
class Add(Binary):
2793class Add(Binary):
2794    pass
class Connector(Binary, Condition):
2797class Connector(Binary, Condition):
2798    pass
class And(Connector):
2801class And(Connector):
2802    pass
class Or(Connector):
2805class Or(Connector):
2806    pass
class BitwiseAnd(Binary):
2809class BitwiseAnd(Binary):
2810    pass
class BitwiseLeftShift(Binary):
2813class BitwiseLeftShift(Binary):
2814    pass
class BitwiseOr(Binary):
2817class BitwiseOr(Binary):
2818    pass
class BitwiseRightShift(Binary):
2821class BitwiseRightShift(Binary):
2822    pass
class BitwiseXor(Binary):
2825class BitwiseXor(Binary):
2826    pass
class Div(Binary):
2829class Div(Binary):
2830    pass
class Dot(Binary):
2833class Dot(Binary):
2834    @property
2835    def name(self) -> str:
2836        return self.expression.name
class DPipe(Binary):
2839class DPipe(Binary):
2840    pass
class EQ(Binary, Predicate):
2843class EQ(Binary, Predicate):
2844    pass
class NullSafeEQ(Binary, Predicate):
2847class NullSafeEQ(Binary, Predicate):
2848    pass
class NullSafeNEQ(Binary, Predicate):
2851class NullSafeNEQ(Binary, Predicate):
2852    pass
class Distance(Binary):
2855class Distance(Binary):
2856    pass
class Escape(Binary):
2859class Escape(Binary):
2860    pass
class Glob(Binary, Predicate):
2863class Glob(Binary, Predicate):
2864    pass
class GT(Binary, Predicate):
2867class GT(Binary, Predicate):
2868    pass
class GTE(Binary, Predicate):
2871class GTE(Binary, Predicate):
2872    pass
class ILike(Binary, Predicate):
2875class ILike(Binary, Predicate):
2876    pass
class ILikeAny(Binary, Predicate):
2879class ILikeAny(Binary, Predicate):
2880    pass
class IntDiv(Binary):
2883class IntDiv(Binary):
2884    pass
class Is(Binary, Predicate):
2887class Is(Binary, Predicate):
2888    pass
class Kwarg(Binary):
2891class Kwarg(Binary):
2892    """Kwarg in special functions like func(kwarg => y)."""

Kwarg in special functions like func(kwarg => y).

class Like(Binary, Predicate):
2895class Like(Binary, Predicate):
2896    pass
class LikeAny(Binary, Predicate):
2899class LikeAny(Binary, Predicate):
2900    pass
class LT(Binary, Predicate):
2903class LT(Binary, Predicate):
2904    pass
class LTE(Binary, Predicate):
2907class LTE(Binary, Predicate):
2908    pass
class Mod(Binary):
2911class Mod(Binary):
2912    pass
class Mul(Binary):
2915class Mul(Binary):
2916    pass
class NEQ(Binary, Predicate):
2919class NEQ(Binary, Predicate):
2920    pass
class SimilarTo(Binary, Predicate):
2923class SimilarTo(Binary, Predicate):
2924    pass
class Slice(Binary):
2927class Slice(Binary):
2928    arg_types = {"this": False, "expression": False}
class Sub(Binary):
2931class Sub(Binary):
2932    pass
class Unary(Expression):
2937class Unary(Expression):
2938    pass
class BitwiseNot(Unary):
2941class BitwiseNot(Unary):
2942    pass
class Not(Unary, Condition):
2945class Not(Unary, Condition):
2946    pass
class Paren(Unary, Condition):
2949class Paren(Unary, Condition):
2950    arg_types = {"this": True, "with": False}
class Neg(Unary):
2953class Neg(Unary):
2954    pass
class Alias(Expression):
2958class Alias(Expression):
2959    arg_types = {"this": True, "alias": False}
2960
2961    @property
2962    def output_name(self):
2963        return self.alias
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
class Aliases(Expression):
2966class Aliases(Expression):
2967    arg_types = {"this": True, "expressions": True}
2968
2969    @property
2970    def aliases(self):
2971        return self.expressions
class AtTimeZone(Expression):
2974class AtTimeZone(Expression):
2975    arg_types = {"this": True, "zone": True}
class Between(Predicate):
2978class Between(Predicate):
2979    arg_types = {"this": True, "low": True, "high": True}
class Bracket(Condition):
2982class Bracket(Condition):
2983    arg_types = {"this": True, "expressions": True}
class Distinct(Expression):
2986class Distinct(Expression):
2987    arg_types = {"expressions": False, "on": False}
class In(Predicate):
2990class In(Predicate):
2991    arg_types = {
2992        "this": True,
2993        "expressions": False,
2994        "query": False,
2995        "unnest": False,
2996        "field": False,
2997        "is_global": False,
2998    }
class TimeUnit(Expression):
3001class TimeUnit(Expression):
3002    """Automatically converts unit arg into a var."""
3003
3004    arg_types = {"unit": False}
3005
3006    def __init__(self, **args):
3007        unit = args.get("unit")
3008        if isinstance(unit, Column):
3009            args["unit"] = Var(this=unit.name)
3010        elif isinstance(unit, Week):
3011            unit.set("this", Var(this=unit.this.name))
3012        super().__init__(**args)

Automatically converts unit arg into a var.

TimeUnit(**args)
3006    def __init__(self, **args):
3007        unit = args.get("unit")
3008        if isinstance(unit, Column):
3009            args["unit"] = Var(this=unit.name)
3010        elif isinstance(unit, Week):
3011            unit.set("this", Var(this=unit.this.name))
3012        super().__init__(**args)
class Interval(TimeUnit):
3015class Interval(TimeUnit):
3016    arg_types = {"this": False, "unit": False}
class IgnoreNulls(Expression):
3019class IgnoreNulls(Expression):
3020    pass
class RespectNulls(Expression):
3023class RespectNulls(Expression):
3024    pass
class Func(Condition):
3028class Func(Condition):
3029    """
3030    The base class for all function expressions.
3031
3032    Attributes:
3033        is_var_len_args (bool): if set to True the last argument defined in arg_types will be
3034            treated as a variable length argument and the argument's value will be stored as a list.
3035        _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items)
3036            for this function expression. These values are used to map this node to a name during parsing
3037            as well as to provide the function's name during SQL string generation. By default the SQL
3038            name is set to the expression's class name transformed to snake case.
3039    """
3040
3041    is_var_len_args = False
3042
3043    @classmethod
3044    def from_arg_list(cls, args):
3045        if cls.is_var_len_args:
3046            all_arg_keys = list(cls.arg_types)
3047            # If this function supports variable length argument treat the last argument as such.
3048            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3049            num_non_var = len(non_var_len_arg_keys)
3050
3051            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3052            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3053        else:
3054            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3055
3056        return cls(**args_dict)
3057
3058    @classmethod
3059    def sql_names(cls):
3060        if cls is Func:
3061            raise NotImplementedError(
3062                "SQL name is only supported by concrete function implementations"
3063            )
3064        if "_sql_names" not in cls.__dict__:
3065            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3066        return cls._sql_names
3067
3068    @classmethod
3069    def sql_name(cls):
3070        return cls.sql_names()[0]
3071
3072    @classmethod
3073    def default_parser_mappings(cls):
3074        return {name: cls.from_arg_list for name in cls.sql_names()}

The base class for all function expressions.

Attributes:
  • is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
  • _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
@classmethod
def from_arg_list(cls, args):
3043    @classmethod
3044    def from_arg_list(cls, args):
3045        if cls.is_var_len_args:
3046            all_arg_keys = list(cls.arg_types)
3047            # If this function supports variable length argument treat the last argument as such.
3048            non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys
3049            num_non_var = len(non_var_len_arg_keys)
3050
3051            args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)}
3052            args_dict[all_arg_keys[-1]] = args[num_non_var:]
3053        else:
3054            args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)}
3055
3056        return cls(**args_dict)
@classmethod
def sql_names(cls):
3058    @classmethod
3059    def sql_names(cls):
3060        if cls is Func:
3061            raise NotImplementedError(
3062                "SQL name is only supported by concrete function implementations"
3063            )
3064        if "_sql_names" not in cls.__dict__:
3065            cls._sql_names = [camel_to_snake_case(cls.__name__)]
3066        return cls._sql_names
@classmethod
def sql_name(cls):
3068    @classmethod
3069    def sql_name(cls):
3070        return cls.sql_names()[0]
@classmethod
def default_parser_mappings(cls):
3072    @classmethod
3073    def default_parser_mappings(cls):
3074        return {name: cls.from_arg_list for name in cls.sql_names()}
class AggFunc(Func):
3077class AggFunc(Func):
3078    pass
class Abs(Func):
3081class Abs(Func):
3082    pass
class Anonymous(Func):
3085class Anonymous(Func):
3086    arg_types = {"this": True, "expressions": False}
3087    is_var_len_args = True
class ApproxDistinct(AggFunc):
3090class ApproxDistinct(AggFunc):
3091    arg_types = {"this": True, "accuracy": False}
class Array(Func):
3094class Array(Func):
3095    arg_types = {"expressions": False}
3096    is_var_len_args = True
class GenerateSeries(Func):
3099class GenerateSeries(Func):
3100    arg_types = {"start": True, "end": True, "step": False}
class ArrayAgg(AggFunc):
3103class ArrayAgg(AggFunc):
3104    pass
class ArrayAll(Func):
3107class ArrayAll(Func):
3108    arg_types = {"this": True, "expression": True}
class ArrayAny(Func):
3111class ArrayAny(Func):
3112    arg_types = {"this": True, "expression": True}
class ArrayConcat(Func):
3115class ArrayConcat(Func):
3116    arg_types = {"this": True, "expressions": False}
3117    is_var_len_args = True
class ArrayContains(Func):
3120class ArrayContains(Func):
3121    arg_types = {"this": True, "expression": True}
class ArrayFilter(Func):
3124class ArrayFilter(Func):
3125    arg_types = {"this": True, "expression": True}
3126    _sql_names = ["FILTER", "ARRAY_FILTER"]
class ArraySize(Func):
3129class ArraySize(Func):
3130    arg_types = {"this": True, "expression": False}
class ArraySort(Func):
3133class ArraySort(Func):
3134    arg_types = {"this": True, "expression": False}
class ArraySum(Func):
3137class ArraySum(Func):
3138    pass
class ArrayUnionAgg(AggFunc):
3141class ArrayUnionAgg(AggFunc):
3142    pass
class Avg(AggFunc):
3145class Avg(AggFunc):
3146    pass
class AnyValue(AggFunc):
3149class AnyValue(AggFunc):
3150    pass
class Case(Func):
3153class Case(Func):
3154    arg_types = {"this": False, "ifs": True, "default": False}
class Cast(Func):
3157class Cast(Func):
3158    arg_types = {"this": True, "to": True}
3159
3160    @property
3161    def name(self) -> str:
3162        return self.this.name
3163
3164    @property
3165    def to(self):
3166        return self.args["to"]
3167
3168    @property
3169    def output_name(self):
3170        return self.name
3171
3172    def is_type(self, dtype: DataType.Type) -> bool:
3173        return self.to.is_type(dtype)
output_name

Name of the output column if this expression is a selection.

If the Expression has no output name, an empty string is returned.

Example:
>>> from sqlglot import parse_one
>>> parse_one("SELECT a").expressions[0].output_name
'a'
>>> parse_one("SELECT b AS c").expressions[0].output_name
'c'
>>> parse_one("SELECT 1 + 2").expressions[0].output_name
''
def is_type(self, dtype: sqlglot.expressions.DataType.Type) -> bool:
3172    def is_type(self, dtype: DataType.Type) -> bool:
3173        return self.to.is_type(dtype)
class Collate(Binary):
3176class Collate(Binary):
3177    pass
class TryCast(Cast):
3180class TryCast(Cast):
3181    pass
class Ceil(Func):
3184class Ceil(Func):
3185    arg_types = {"this": True, "decimals": False}
3186    _sql_names = ["CEIL", "CEILING"]
class Coalesce(Func):
3189class Coalesce(Func):
3190    arg_types = {"this": True, "expressions": False}
3191    is_var_len_args = True
class Concat(Func):
3194class Concat(Func):
3195    arg_types = {"expressions": True}
3196    is_var_len_args = True
class ConcatWs(Concat):
3199class ConcatWs(Concat):
3200    _sql_names = ["CONCAT_WS"]
class Count(AggFunc):
3203class Count(AggFunc):
3204    arg_types = {"this": False}
class CurrentDate(Func):
3207class CurrentDate(Func):
3208    arg_types = {"this": False}
class CurrentDatetime(Func):
3211class CurrentDatetime(Func):
3212    arg_types = {"this": False}
class CurrentTime(Func):
3215class CurrentTime(Func):
3216    arg_types = {"this": False}
class CurrentTimestamp(Func):
3219class CurrentTimestamp(Func):
3220    arg_types = {"this": False}
class DateAdd(Func, TimeUnit):
3223class DateAdd(Func, TimeUnit):
3224    arg_types = {"this": True, "expression": True, "unit": False}
class DateSub(Func, TimeUnit):
3227class DateSub(Func, TimeUnit):
3228    arg_types = {"this": True, "expression": True, "unit": False}
class DateDiff(Func, TimeUnit):
3231class DateDiff(Func, TimeUnit):
3232    arg_types = {"this": True, "expression": True, "unit": False}
class DateTrunc(Func):
3235class DateTrunc(Func):
3236    arg_types = {"unit": True, "this": True, "zone": False}
class DatetimeAdd(Func, TimeUnit):
3239class DatetimeAdd(Func, TimeUnit):
3240    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeSub(Func, TimeUnit):
3243class DatetimeSub(Func, TimeUnit):
3244    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeDiff(Func, TimeUnit):
3247class DatetimeDiff(Func, TimeUnit):
3248    arg_types = {"this": True, "expression": True, "unit": False}
class DatetimeTrunc(Func, TimeUnit):
3251class DatetimeTrunc(Func, TimeUnit):
3252    arg_types = {"this": True, "unit": True, "zone": False}
class DayOfWeek(Func):
3255class DayOfWeek(Func):
3256    _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"]
class DayOfMonth(Func):
3259class DayOfMonth(Func):
3260    _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"]
class DayOfYear(Func):
3263class DayOfYear(Func):
3264    _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"]
class WeekOfYear(Func):
3267class WeekOfYear(Func):
3268    _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"]
class LastDateOfMonth(Func):
3271class LastDateOfMonth(Func):
3272    pass
class Extract(Func):
3275class Extract(Func):
3276    arg_types = {"this": True, "expression": True}
class TimestampAdd(Func, TimeUnit):
3279class TimestampAdd(Func, TimeUnit):
3280    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampSub(Func, TimeUnit):
3283class TimestampSub(Func, TimeUnit):
3284    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampDiff(Func, TimeUnit):
3287class TimestampDiff(Func, TimeUnit):
3288    arg_types = {"this": True, "expression": True, "unit": False}
class TimestampTrunc(Func, TimeUnit):
3291class TimestampTrunc(Func, TimeUnit):
3292    arg_types = {"this": True, "unit": True, "zone": False}
class TimeAdd(Func, TimeUnit):
3295class TimeAdd(Func, TimeUnit):
3296    arg_types = {"this": True, "expression": True, "unit": False}
class TimeSub(Func, TimeUnit):
3299class TimeSub(Func, TimeUnit):
3300    arg_types = {"this": True, "expression": True, "unit": False}
class TimeDiff(Func, TimeUnit):
3303class TimeDiff(Func, TimeUnit):
3304    arg_types = {"this": True, "expression": True, "unit": False}
class TimeTrunc(Func, TimeUnit):
3307class TimeTrunc(Func, TimeUnit):
3308    arg_types = {"this": True, "unit": True, "zone": False}
class DateFromParts(Func):
3311class DateFromParts(Func):
3312    _sql_names = ["DATEFROMPARTS"]
3313    arg_types = {"year": True, "month": True, "day": True}
class DateStrToDate(Func):
3316class DateStrToDate(Func):
3317    pass
class DateToDateStr(Func):
3320class DateToDateStr(Func):
3321    pass
class DateToDi(Func):
3324class DateToDi(Func):
3325    pass
class Day(Func):
3328class Day(Func):
3329    pass
class Decode(Func):
3332class Decode(Func):
3333    arg_types = {"this": True, "charset": True, "replace": False}
class DiToDate(Func):
3336class DiToDate(Func):
3337    pass
class Encode(Func):
3340class Encode(Func):
3341    arg_types = {"this": True, "charset": True}
class Exp(Func):
3344class Exp(Func):
3345    pass
class Explode(Func):
3348class Explode(Func):
3349    pass
class Floor(Func):
3352class Floor(Func):
3353    arg_types = {"this": True, "decimals": False}
class Greatest(Func):
3356class Greatest(Func):
3357    arg_types = {"this": True, "expressions": False}
3358    is_var_len_args = True
class GroupConcat(Func):
3361class GroupConcat(Func):
3362    arg_types = {"this": True, "separator": False}
class Hex(Func):
3365class Hex(Func):
3366    pass
class If(Func):
3369class If(Func):
3370    arg_types = {"this": True, "true": True, "false": False}
class IfNull(Func):
3373class IfNull(Func):
3374    arg_types = {"this": True, "expression": False}
3375    _sql_names = ["IFNULL", "NVL"]
class Initcap(Func):
3378class Initcap(Func):
3379    pass
class JSONBContains(Binary):
3382class JSONBContains(Binary):
3383    _sql_names = ["JSONB_CONTAINS"]
class JSONExtract(Binary, Func):
3386class JSONExtract(Binary, Func):
3387    _sql_names = ["JSON_EXTRACT"]
class JSONExtractScalar(JSONExtract):
3390class JSONExtractScalar(JSONExtract):
3391    _sql_names = ["JSON_EXTRACT_SCALAR"]
class JSONBExtract(JSONExtract):
3394class JSONBExtract(JSONExtract):
3395    _sql_names = ["JSONB_EXTRACT"]
class JSONBExtractScalar(JSONExtract):
3398class JSONBExtractScalar(JSONExtract):
3399    _sql_names = ["JSONB_EXTRACT_SCALAR"]
class Least(Func):
3402class Least(Func):
3403    arg_types = {"this": True, "expressions": False}
3404    is_var_len_args = True
class Length(Func):
3407class Length(Func):
3408    pass
class Levenshtein(Func):
3411class Levenshtein(Func):
3412    arg_types = {
3413        "this": True,
3414        "expression": False,
3415        "ins_cost": False,
3416        "del_cost": False,
3417        "sub_cost": False,
3418    }
class Ln(Func):
3421class Ln(Func):
3422    pass
class Log(Func):
3425class Log(Func):
3426    arg_types = {"this": True, "expression": False}
class Log2(Func):
3429class Log2(Func):
3430    pass
class Log10(Func):
3433class Log10(Func):
3434    pass
class LogicalOr(AggFunc):
3437class LogicalOr(AggFunc):
3438    _sql_names = ["LOGICAL_OR", "BOOL_OR"]
class Lower(Func):
3441class Lower(Func):
3442    _sql_names = ["LOWER", "LCASE"]
class Map(Func):
3445class Map(Func):
3446    arg_types = {"keys": False, "values": False}
class VarMap(Func):
3449class VarMap(Func):
3450    arg_types = {"keys": True, "values": True}
3451    is_var_len_args = True
class Matches(Func):
3454class Matches(Func):
3455    """Oracle/Snowflake decode.
3456    https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm
3457    Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
3458    """
3459
3460    arg_types = {"this": True, "expressions": True}
3461    is_var_len_args = True

Oracle/Snowflake decode. https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)

class Max(AggFunc):
3464class Max(AggFunc):
3465    arg_types = {"this": True, "expression": False}
class Min(AggFunc):
3468class Min(AggFunc):
3469    arg_types = {"this": True, "expression": False}
class Month(Func):
3472class Month(Func):
3473    pass
class Nvl2(Func):
3476class Nvl2(Func):
3477    arg_types = {"this": True, "true": True, "false": False}
class Posexplode(Func):
3480class Posexplode(Func):
3481    pass
class Pow(Binary, Func):
3484class Pow(Binary, Func):
3485    _sql_names = ["POWER", "POW"]
class PercentileCont(AggFunc):
3488class PercentileCont(AggFunc):
3489    pass
class PercentileDisc(AggFunc):
3492class PercentileDisc(AggFunc):
3493    pass
class Quantile(AggFunc):
3496class Quantile(AggFunc):
3497    arg_types = {"this": True, "quantile": True}
class Quantiles(AggFunc):
3502class Quantiles(AggFunc):
3503    arg_types = {"parameters": True, "expressions": True}
class QuantileIf(AggFunc):
3506class QuantileIf(AggFunc):
3507    arg_types = {"parameters": True, "expressions": True}
class ApproxQuantile(Quantile):
3510class ApproxQuantile(Quantile):
3511    arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
class ReadCSV(Func):
3514class ReadCSV(Func):
3515    _sql_names = ["READ_CSV"]
3516    is_var_len_args = True
3517    arg_types = {"this": True, "expressions": False}
class Reduce(Func):
3520class Reduce(Func):
3521    arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
class RegexpExtract(Func):
3524class RegexpExtract(Func):
3525    arg_types = {
3526        "this": True,
3527        "expression": True,
3528        "position": False,
3529        "occurrence": False,
3530        "group": False,
3531    }
class RegexpLike(Func):
3534class RegexpLike(Func):
3535    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpILike(Func):
3538class RegexpILike(Func):
3539    arg_types = {"this": True, "expression": True, "flag": False}
class RegexpSplit(Func):
3542class RegexpSplit(Func):
3543    arg_types = {"this": True, "expression": True}
class Repeat(Func):
3546class Repeat(Func):
3547    arg_types = {"this": True, "times": True}
class Round(Func):
3550class Round(Func):
3551    arg_types = {"this": True, "decimals": False}
class RowNumber(Func):
3554class RowNumber(Func):
3555    arg_types: t.Dict[str, t.Any] = {}
class SafeDivide(Func):
3558class SafeDivide(Func):
3559    arg_types = {"this": True, "expression": True}
class SetAgg(AggFunc):
3562class SetAgg(AggFunc):
3563    pass
class SortArray(Func):
3566class SortArray(Func):
3567    arg_types = {"this": True, "asc": False}
class Split(Func):
3570class Split(Func):
3571    arg_types = {"this": True, "expression": True, "limit": False}
class Substring(Func):
3576class Substring(Func):
3577    arg_types = {"this": True, "start": False, "length": False}
class StrPosition(Func):
3580class StrPosition(Func):
3581    arg_types = {
3582        "this": True,
3583        "substr": True,
3584        "position": False,
3585        "instance": False,
3586    }
class StrToDate(Func):
3589class StrToDate(Func):
3590    arg_types = {"this": True, "format": True}
class StrToTime(Func):
3593class StrToTime(Func):
3594    arg_types = {"this": True, "format": True}
class StrToUnix(Func):
3599class StrToUnix(Func):
3600    arg_types = {"this": False, "format": False}
class NumberToStr(Func):
3603class NumberToStr(Func):
3604    arg_types = {"this": True, "format": True}
class Struct(Func):
3607class Struct(Func):
3608    arg_types = {"expressions": True}
3609    is_var_len_args = True
class StructExtract(Func):
3612class StructExtract(Func):
3613    arg_types = {"this": True, "expression": True}
class Sum(AggFunc):
3616class Sum(AggFunc):
3617    pass
class Sqrt(Func):
3620class Sqrt(Func):
3621    pass
class Stddev(AggFunc):
3624class Stddev(AggFunc):
3625    pass
class StddevPop(AggFunc):
3628class StddevPop(AggFunc):
3629    pass
class StddevSamp(AggFunc):
3632class StddevSamp(AggFunc):
3633    pass
class TimeToStr(Func):
3636class TimeToStr(Func):
3637    arg_types = {"this": True, "format": True}
class TimeToTimeStr(Func):
3640class TimeToTimeStr(Func):
3641    pass
class TimeToUnix(Func):
3644class TimeToUnix(Func):
3645    pass
class TimeStrToDate(Func):
3648class TimeStrToDate(Func):
3649    pass
class TimeStrToTime(Func):
3652class TimeStrToTime(Func):
3653    pass
class TimeStrToUnix(Func):
3656class TimeStrToUnix(Func):
3657    pass
class Trim(Func):
3660class Trim(Func):
3661    arg_types = {
3662        "this": True,
3663        "expression": False,
3664        "position": False,
3665        "collation": False,
3666    }
class TsOrDsAdd(Func, TimeUnit):
3669class TsOrDsAdd(Func, TimeUnit):
3670    arg_types = {"this": True, "expression": True, "unit": False}
class TsOrDsToDateStr(Func):
3673class TsOrDsToDateStr(Func):
3674    pass
class TsOrDsToDate(Func):
3677class TsOrDsToDate(Func):
3678    arg_types = {"this": True, "format": False}
class TsOrDiToDi(Func):
3681class TsOrDiToDi(Func):
3682    pass
class Unhex(Func):
3685class Unhex(Func):
3686    pass
class UnixToStr(Func):
3689class UnixToStr(Func):
3690    arg_types = {"this": True, "format": False}
class UnixToTime(Func):
3695class UnixToTime(Func):
3696    arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False}
3697
3698    SECONDS = Literal.string("seconds")
3699    MILLIS = Literal.string("millis")
3700    MICROS = Literal.string("micros")
class UnixToTimeStr(Func):
3703class UnixToTimeStr(Func):
3704    pass
class Upper(Func):
3707class Upper(Func):
3708    _sql_names = ["UPPER", "UCASE"]
class Variance(AggFunc):
3711class Variance(AggFunc):
3712    _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"]
class VariancePop(AggFunc):
3715class VariancePop(AggFunc):
3716    _sql_names = ["VARIANCE_POP", "VAR_POP"]
class Week(Func):
3719class Week(Func):
3720    arg_types = {"this": True, "mode": False}
class XMLTable(Func):
3723class XMLTable(Func):
3724    arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
class Year(Func):
3727class Year(Func):
3728    pass
class Use(Expression):
3731class Use(Expression):
3732    arg_types = {"this": True, "kind": False}
class Merge(Expression):
3735class Merge(Expression):
3736    arg_types = {"this": True, "using": True, "on": True, "expressions": True}
class When(Func):
3739class When(Func):
3740    arg_types = {"this": True, "then": True}
def maybe_parse( sql_or_expression: str | sqlglot.expressions.Expression, *, into: Union[str, Type[sqlglot.expressions.Expression], Collection[Union[str, Type[sqlglot.expressions.Expression]]], NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, prefix: Optional[str] = None, copy: bool = False, **opts) -> sqlglot.expressions.Expression:
3768def maybe_parse(
3769    sql_or_expression: str | Expression,
3770    *,
3771    into: t.Optional[IntoType] = None,
3772    dialect: DialectType = None,
3773    prefix: t.Optional[str] = None,
3774    copy: bool = False,
3775    **opts,
3776) -> Expression:
3777    """Gracefully handle a possible string or expression.
3778
3779    Example:
3780        >>> maybe_parse("1")
3781        (LITERAL this: 1, is_string: False)
3782        >>> maybe_parse(to_identifier("x"))
3783        (IDENTIFIER this: x, quoted: False)
3784
3785    Args:
3786        sql_or_expression: the SQL code string or an expression
3787        into: the SQLGlot Expression to parse into
3788        dialect: the dialect used to parse the input expressions (in the case that an
3789            input expression is a SQL string).
3790        prefix: a string to prefix the sql with before it gets parsed
3791            (automatically includes a space)
3792        copy: whether or not to copy the expression.
3793        **opts: other options to use to parse the input expressions (again, in the case
3794            that an input expression is a SQL string).
3795
3796    Returns:
3797        Expression: the parsed or given expression.
3798    """
3799    if isinstance(sql_or_expression, Expression):
3800        if copy:
3801            return sql_or_expression.copy()
3802        return sql_or_expression
3803
3804    import sqlglot
3805
3806    sql = str(sql_or_expression)
3807    if prefix:
3808        sql = f"{prefix} {sql}"
3809    return sqlglot.parse_one(sql, read=dialect, into=into, **opts)

Gracefully handle a possible string or expression.

Example:
>>> maybe_parse("1")
(LITERAL this: 1, is_string: False)
>>> maybe_parse(to_identifier("x"))
(IDENTIFIER this: x, quoted: False)
Arguments:
  • sql_or_expression: the SQL code string or an expression
  • into: the SQLGlot Expression to parse into
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
  • copy: whether or not to copy the expression.
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Expression: the parsed or given expression.

def union(left, right, distinct=True, dialect=None, **opts):
3955def union(left, right, distinct=True, dialect=None, **opts):
3956    """
3957    Initializes a syntax tree from one UNION expression.
3958
3959    Example:
3960        >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
3961        'SELECT * FROM foo UNION SELECT * FROM bla'
3962
3963    Args:
3964        left (str | Expression): the SQL code string corresponding to the left-hand side.
3965            If an `Expression` instance is passed, it will be used as-is.
3966        right (str | Expression): the SQL code string corresponding to the right-hand side.
3967            If an `Expression` instance is passed, it will be used as-is.
3968        distinct (bool): set the DISTINCT flag if and only if this is true.
3969        dialect (str): the dialect used to parse the input expression.
3970        opts (kwargs): other options to use to parse the input expressions.
3971    Returns:
3972        Union: the syntax tree for the UNION expression.
3973    """
3974    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
3975    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
3976
3977    return Union(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one UNION expression.

Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Union: the syntax tree for the UNION expression.

def intersect(left, right, distinct=True, dialect=None, **opts):
3980def intersect(left, right, distinct=True, dialect=None, **opts):
3981    """
3982    Initializes a syntax tree from one INTERSECT expression.
3983
3984    Example:
3985        >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
3986        'SELECT * FROM foo INTERSECT SELECT * FROM bla'
3987
3988    Args:
3989        left (str | Expression): the SQL code string corresponding to the left-hand side.
3990            If an `Expression` instance is passed, it will be used as-is.
3991        right (str | Expression): the SQL code string corresponding to the right-hand side.
3992            If an `Expression` instance is passed, it will be used as-is.
3993        distinct (bool): set the DISTINCT flag if and only if this is true.
3994        dialect (str): the dialect used to parse the input expression.
3995        opts (kwargs): other options to use to parse the input expressions.
3996    Returns:
3997        Intersect: the syntax tree for the INTERSECT expression.
3998    """
3999    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4000    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4001
4002    return Intersect(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one INTERSECT expression.

Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Intersect: the syntax tree for the INTERSECT expression.

def except_(left, right, distinct=True, dialect=None, **opts):
4005def except_(left, right, distinct=True, dialect=None, **opts):
4006    """
4007    Initializes a syntax tree from one EXCEPT expression.
4008
4009    Example:
4010        >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
4011        'SELECT * FROM foo EXCEPT SELECT * FROM bla'
4012
4013    Args:
4014        left (str | Expression): the SQL code string corresponding to the left-hand side.
4015            If an `Expression` instance is passed, it will be used as-is.
4016        right (str | Expression): the SQL code string corresponding to the right-hand side.
4017            If an `Expression` instance is passed, it will be used as-is.
4018        distinct (bool): set the DISTINCT flag if and only if this is true.
4019        dialect (str): the dialect used to parse the input expression.
4020        opts (kwargs): other options to use to parse the input expressions.
4021    Returns:
4022        Except: the syntax tree for the EXCEPT statement.
4023    """
4024    left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts)
4025    right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts)
4026
4027    return Except(this=left, expression=right, distinct=distinct)

Initializes a syntax tree from one EXCEPT expression.

Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql()
'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
  • left (str | Expression): the SQL code string corresponding to the left-hand side. If an Expression instance is passed, it will be used as-is.
  • right (str | Expression): the SQL code string corresponding to the right-hand side. If an Expression instance is passed, it will be used as-is.
  • distinct (bool): set the DISTINCT flag if and only if this is true.
  • dialect (str): the dialect used to parse the input expression.
  • opts (kwargs): other options to use to parse the input expressions.
Returns:

Except: the syntax tree for the EXCEPT statement.

def select( *expressions: str | sqlglot.expressions.Expression, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> sqlglot.expressions.Select:
4030def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select:
4031    """
4032    Initializes a syntax tree from one or multiple SELECT expressions.
4033
4034    Example:
4035        >>> select("col1", "col2").from_("tbl").sql()
4036        'SELECT col1, col2 FROM tbl'
4037
4038    Args:
4039        *expressions: the SQL code string to parse as the expressions of a
4040            SELECT statement. If an Expression instance is passed, this is used as-is.
4041        dialect: the dialect used to parse the input expressions (in the case that an
4042            input expression is a SQL string).
4043        **opts: other options to use to parse the input expressions (again, in the case
4044            that an input expression is a SQL string).
4045
4046    Returns:
4047        Select: the syntax tree for the SELECT statement.
4048    """
4049    return Select().select(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from one or multiple SELECT expressions.

Example:
>>> select("col1", "col2").from_("tbl").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def from_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Select:
4052def from_(*expressions, dialect=None, **opts) -> Select:
4053    """
4054    Initializes a syntax tree from a FROM expression.
4055
4056    Example:
4057        >>> from_("tbl").select("col1", "col2").sql()
4058        'SELECT col1, col2 FROM tbl'
4059
4060    Args:
4061        *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a
4062            SELECT statement. If an Expression instance is passed, this is used as-is.
4063        dialect (str): the dialect used to parse the input expression (in the case that the
4064            input expression is a SQL string).
4065        **opts: other options to use to parse the input expressions (again, in the case
4066            that the input expression is a SQL string).
4067
4068    Returns:
4069        Select: the syntax tree for the SELECT statement.
4070    """
4071    return Select().from_(*expressions, dialect=dialect, **opts)

Initializes a syntax tree from a FROM expression.

Example:
>>> from_("tbl").select("col1", "col2").sql()
'SELECT col1, col2 FROM tbl'
Arguments:
  • *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Select: the syntax tree for the SELECT statement.

def update( table, properties, where=None, from_=None, dialect=None, **opts) -> sqlglot.expressions.Update:
4074def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update:
4075    """
4076    Creates an update statement.
4077
4078    Example:
4079        >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
4080        "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
4081
4082    Args:
4083        *properties (Dict[str, Any]): dictionary of properties to set which are
4084            auto converted to sql objects eg None -> NULL
4085        where (str): sql conditional parsed into a WHERE statement
4086        from_ (str): sql statement parsed into a FROM statement
4087        dialect (str): the dialect used to parse the input expressions.
4088        **opts: other options to use to parse the input expressions.
4089
4090    Returns:
4091        Update: the syntax tree for the UPDATE statement.
4092    """
4093    update = Update(this=maybe_parse(table, into=Table, dialect=dialect))
4094    update.set(
4095        "expressions",
4096        [
4097            EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v))
4098            for k, v in properties.items()
4099        ],
4100    )
4101    if from_:
4102        update.set(
4103            "from",
4104            maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts),
4105        )
4106    if isinstance(where, Condition):
4107        where = Where(this=where)
4108    if where:
4109        update.set(
4110            "where",
4111            maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4112        )
4113    return update

Creates an update statement.

Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql()
"UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
  • *properties (Dict[str, Any]): dictionary of properties to set which are auto converted to sql objects eg None -> NULL
  • where (str): sql conditional parsed into a WHERE statement
  • from_ (str): sql statement parsed into a FROM statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Update: the syntax tree for the UPDATE statement.

def delete(table, where=None, dialect=None, **opts) -> sqlglot.expressions.Delete:
4116def delete(table, where=None, dialect=None, **opts) -> Delete:
4117    """
4118    Builds a delete statement.
4119
4120    Example:
4121        >>> delete("my_table", where="id > 1").sql()
4122        'DELETE FROM my_table WHERE id > 1'
4123
4124    Args:
4125        where (str|Condition): sql conditional parsed into a WHERE statement
4126        dialect (str): the dialect used to parse the input expressions.
4127        **opts: other options to use to parse the input expressions.
4128
4129    Returns:
4130        Delete: the syntax tree for the DELETE statement.
4131    """
4132    return Delete(
4133        this=maybe_parse(table, into=Table, dialect=dialect, **opts),
4134        where=Where(this=where)
4135        if isinstance(where, Condition)
4136        else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts),
4137    )

Builds a delete statement.

Example:
>>> delete("my_table", where="id > 1").sql()
'DELETE FROM my_table WHERE id > 1'
Arguments:
  • where (str|Condition): sql conditional parsed into a WHERE statement
  • dialect (str): the dialect used to parse the input expressions.
  • **opts: other options to use to parse the input expressions.
Returns:

Delete: the syntax tree for the DELETE statement.

def condition(expression, dialect=None, **opts) -> sqlglot.expressions.Condition:
4140def condition(expression, dialect=None, **opts) -> Condition:
4141    """
4142    Initialize a logical condition expression.
4143
4144    Example:
4145        >>> condition("x=1").sql()
4146        'x = 1'
4147
4148        This is helpful for composing larger logical syntax trees:
4149        >>> where = condition("x=1")
4150        >>> where = where.and_("y=1")
4151        >>> Select().from_("tbl").select("*").where(where).sql()
4152        'SELECT * FROM tbl WHERE x = 1 AND y = 1'
4153
4154    Args:
4155        *expression (str | Expression): the SQL code string to parse.
4156            If an Expression instance is passed, this is used as-is.
4157        dialect (str): the dialect used to parse the input expression (in the case that the
4158            input expression is a SQL string).
4159        **opts: other options to use to parse the input expressions (again, in the case
4160            that the input expression is a SQL string).
4161
4162    Returns:
4163        Condition: the expression
4164    """
4165    return maybe_parse(  # type: ignore
4166        expression,
4167        into=Condition,
4168        dialect=dialect,
4169        **opts,
4170    )

Initialize a logical condition expression.

Example:
>>> condition("x=1").sql()
'x = 1'

This is helpful for composing larger logical syntax trees:

>>> where = condition("x=1")
>>> where = where.and_("y=1")
>>> Select().from_("tbl").select("*").where(where).sql()
'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
  • *expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
  • **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:

Condition: the expression

def and_(*expressions, dialect=None, **opts) -> sqlglot.expressions.And:
4173def and_(*expressions, dialect=None, **opts) -> And:
4174    """
4175    Combine multiple conditions with an AND logical operator.
4176
4177    Example:
4178        >>> and_("x=1", and_("y=1", "z=1")).sql()
4179        'x = 1 AND (y = 1 AND z = 1)'
4180
4181    Args:
4182        *expressions (str | Expression): the SQL code strings to parse.
4183            If an Expression instance is passed, this is used as-is.
4184        dialect (str): the dialect used to parse the input expression.
4185        **opts: other options to use to parse the input expressions.
4186
4187    Returns:
4188        And: the new condition
4189    """
4190    return _combine(expressions, And, dialect, **opts)

Combine multiple conditions with an AND logical operator.

Example:
>>> and_("x=1", and_("y=1", "z=1")).sql()
'x = 1 AND (y = 1 AND z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

And: the new condition

def or_(*expressions, dialect=None, **opts) -> sqlglot.expressions.Or:
4193def or_(*expressions, dialect=None, **opts) -> Or:
4194    """
4195    Combine multiple conditions with an OR logical operator.
4196
4197    Example:
4198        >>> or_("x=1", or_("y=1", "z=1")).sql()
4199        'x = 1 OR (y = 1 OR z = 1)'
4200
4201    Args:
4202        *expressions (str | Expression): the SQL code strings to parse.
4203            If an Expression instance is passed, this is used as-is.
4204        dialect (str): the dialect used to parse the input expression.
4205        **opts: other options to use to parse the input expressions.
4206
4207    Returns:
4208        Or: the new condition
4209    """
4210    return _combine(expressions, Or, dialect, **opts)

Combine multiple conditions with an OR logical operator.

Example:
>>> or_("x=1", or_("y=1", "z=1")).sql()
'x = 1 OR (y = 1 OR z = 1)'
Arguments:
  • *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Or: the new condition

def not_(expression, dialect=None, **opts) -> sqlglot.expressions.Not:
4213def not_(expression, dialect=None, **opts) -> Not:
4214    """
4215    Wrap a condition with a NOT operator.
4216
4217    Example:
4218        >>> not_("this_suit='black'").sql()
4219        "NOT this_suit = 'black'"
4220
4221    Args:
4222        expression (str | Expression): the SQL code strings to parse.
4223            If an Expression instance is passed, this is used as-is.
4224        dialect (str): the dialect used to parse the input expression.
4225        **opts: other options to use to parse the input expressions.
4226
4227    Returns:
4228        Not: the new condition
4229    """
4230    this = condition(
4231        expression,
4232        dialect=dialect,
4233        **opts,
4234    )
4235    return Not(this=_wrap_operator(this))

Wrap a condition with a NOT operator.

Example:
>>> not_("this_suit='black'").sql()
"NOT this_suit = 'black'"
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Not: the new condition

def paren(expression) -> sqlglot.expressions.Paren:
4238def paren(expression) -> Paren:
4239    return Paren(this=expression)
def to_identifier(name, quoted=None):
4255def to_identifier(name, quoted=None):
4256    """Builds an identifier.
4257
4258    Args:
4259        name: The name to turn into an identifier.
4260        quoted: Whether or not force quote the identifier.
4261
4262    Returns:
4263        The identifier ast node.
4264    """
4265
4266    if name is None:
4267        return None
4268
4269    if isinstance(name, Identifier):
4270        identifier = name
4271    elif isinstance(name, str):
4272        identifier = Identifier(
4273            this=name,
4274            quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted,
4275        )
4276    else:
4277        raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}")
4278    return identifier

Builds an identifier.

Arguments:
  • name: The name to turn into an identifier.
  • quoted: Whether or not force quote the identifier.
Returns:

The identifier ast node.

def to_interval( interval: str | sqlglot.expressions.Literal) -> sqlglot.expressions.Interval:
4284def to_interval(interval: str | Literal) -> Interval:
4285    """Builds an interval expression from a string like '1 day' or '5 months'."""
4286    if isinstance(interval, Literal):
4287        if not interval.is_string:
4288            raise ValueError("Invalid interval string.")
4289
4290        interval = interval.this
4291
4292    interval_parts = INTERVAL_STRING_RE.match(interval)  # type: ignore
4293
4294    if not interval_parts:
4295        raise ValueError("Invalid interval string.")
4296
4297    return Interval(
4298        this=Literal.string(interval_parts.group(1)),
4299        unit=Var(this=interval_parts.group(2)),
4300    )

Builds an interval expression from a string like '1 day' or '5 months'.

def to_table( sql_path: Union[str, sqlglot.expressions.Table, NoneType], **kwargs) -> Optional[sqlglot.expressions.Table]:
4313def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]:
4314    """
4315    Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional.
4316    If a table is passed in then that table is returned.
4317
4318    Args:
4319        sql_path: a `[catalog].[schema].[table]` string.
4320
4321    Returns:
4322        A table expression.
4323    """
4324    if sql_path is None or isinstance(sql_path, Table):
4325        return sql_path
4326    if not isinstance(sql_path, str):
4327        raise ValueError(f"Invalid type provided for a table: {type(sql_path)}")
4328
4329    catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3))
4330    return Table(this=table_name, db=db, catalog=catalog, **kwargs)

Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional. If a table is passed in then that table is returned.

Arguments:
  • sql_path: a [catalog].[schema].[table] string.
Returns:

A table expression.

def to_column( sql_path: str | sqlglot.expressions.Column, **kwargs) -> sqlglot.expressions.Column:
4333def to_column(sql_path: str | Column, **kwargs) -> Column:
4334    """
4335    Create a column from a `[table].[column]` sql path. Schema is optional.
4336
4337    If a column is passed in then that column is returned.
4338
4339    Args:
4340        sql_path: `[table].[column]` string
4341    Returns:
4342        Table: A column expression
4343    """
4344    if sql_path is None or isinstance(sql_path, Column):
4345        return sql_path
4346    if not isinstance(sql_path, str):
4347        raise ValueError(f"Invalid type provided for column: {type(sql_path)}")
4348    table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2))
4349    return Column(this=column_name, table=table_name, **kwargs)

Create a column from a [table].[column] sql path. Schema is optional.

If a column is passed in then that column is returned.

Arguments:
  • sql_path: [table].[column] string
Returns:

Table: A column expression

def alias_( expression: str | sqlglot.expressions.Expression, alias: str | sqlglot.expressions.Identifier, table: Union[bool, Sequence[str | sqlglot.expressions.Identifier]] = False, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts):
4352def alias_(
4353    expression: str | Expression,
4354    alias: str | Identifier,
4355    table: bool | t.Sequence[str | Identifier] = False,
4356    quoted: t.Optional[bool] = None,
4357    dialect: DialectType = None,
4358    **opts,
4359):
4360    """Create an Alias expression.
4361
4362    Example:
4363        >>> alias_('foo', 'bar').sql()
4364        'foo AS bar'
4365
4366        >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
4367        '(SELECT 1, 2) AS bar(a, b)'
4368
4369    Args:
4370        expression: the SQL code strings to parse.
4371            If an Expression instance is passed, this is used as-is.
4372        alias: the alias name to use. If the name has
4373            special characters it is quoted.
4374        table: Whether or not to create a table alias, can also be a list of columns.
4375        quoted: whether or not to quote the alias
4376        dialect: the dialect used to parse the input expression.
4377        **opts: other options to use to parse the input expressions.
4378
4379    Returns:
4380        Alias: the aliased expression
4381    """
4382    exp = maybe_parse(expression, dialect=dialect, **opts)
4383    alias = to_identifier(alias, quoted=quoted)
4384
4385    if table:
4386        table_alias = TableAlias(this=alias)
4387        exp.set("alias", table_alias)
4388
4389        if not isinstance(table, bool):
4390            for column in table:
4391                table_alias.append("columns", to_identifier(column, quoted=quoted))
4392
4393        return exp
4394
4395    # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in
4396    # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node
4397    # for the complete Window expression.
4398    #
4399    # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls
4400
4401    if "alias" in exp.arg_types and not isinstance(exp, Window):
4402        exp = exp.copy()
4403        exp.set("alias", alias)
4404        return exp
4405    return Alias(this=exp, alias=alias)

Create an Alias expression.

Example:
>>> alias_('foo', 'bar').sql()
'foo AS bar'
>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql()
'(SELECT 1, 2) AS bar(a, b)'
Arguments:
  • expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias: the alias name to use. If the name has special characters it is quoted.
  • table: Whether or not to create a table alias, can also be a list of columns.
  • quoted: whether or not to quote the alias
  • dialect: the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Alias: the aliased expression

def subquery(expression, alias=None, dialect=None, **opts):
4408def subquery(expression, alias=None, dialect=None, **opts):
4409    """
4410    Build a subquery expression.
4411
4412    Example:
4413        >>> subquery('select x from tbl', 'bar').select('x').sql()
4414        'SELECT x FROM (SELECT x FROM tbl) AS bar'
4415
4416    Args:
4417        expression (str | Expression): the SQL code strings to parse.
4418            If an Expression instance is passed, this is used as-is.
4419        alias (str | Expression): the alias name to use.
4420        dialect (str): the dialect used to parse the input expression.
4421        **opts: other options to use to parse the input expressions.
4422
4423    Returns:
4424        Select: a new select with the subquery expression included
4425    """
4426
4427    expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias)
4428    return Select().from_(expression, dialect=dialect, **opts)

Build a subquery expression.

Example:
>>> subquery('select x from tbl', 'bar').select('x').sql()
'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
  • expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
  • alias (str | Expression): the alias name to use.
  • dialect (str): the dialect used to parse the input expression.
  • **opts: other options to use to parse the input expressions.
Returns:

Select: a new select with the subquery expression included

def column( col: str | sqlglot.expressions.Identifier, table: Union[str, sqlglot.expressions.Identifier, NoneType] = None, schema: Union[str, sqlglot.expressions.Identifier, NoneType] = None, quoted: Optional[bool] = None) -> sqlglot.expressions.Column:
4431def column(
4432    col: str | Identifier,
4433    table: t.Optional[str | Identifier] = None,
4434    schema: t.Optional[str | Identifier] = None,
4435    quoted: t.Optional[bool] = None,
4436) -> Column:
4437    """
4438    Build a Column.
4439
4440    Args:
4441        col: column name
4442        table: table name
4443        schema: schema name
4444        quoted: whether or not to force quote each part
4445    Returns:
4446        Column: column instance
4447    """
4448    return Column(
4449        this=to_identifier(col, quoted=quoted),
4450        table=to_identifier(table, quoted=quoted),
4451        schema=to_identifier(schema, quoted=quoted),
4452    )

Build a Column.

Arguments:
  • col: column name
  • table: table name
  • schema: schema name
  • quoted: whether or not to force quote each part
Returns:

Column: column instance

4455def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast:
4456    """Cast an expression to a data type.
4457
4458    Example:
4459        >>> cast('x + 1', 'int').sql()
4460        'CAST(x + 1 AS INT)'
4461
4462    Args:
4463        expression: The expression to cast.
4464        to: The datatype to cast to.
4465
4466    Returns:
4467        A cast node.
4468    """
4469    expression = maybe_parse(expression, **opts)
4470    return Cast(this=expression, to=DataType.build(to, **opts))

Cast an expression to a data type.

Example:
>>> cast('x + 1', 'int').sql()
'CAST(x + 1 AS INT)'
Arguments:
  • expression: The expression to cast.
  • to: The datatype to cast to.
Returns:

A cast node.

def table_( table, db=None, catalog=None, quoted=None, alias=None) -> sqlglot.expressions.Table:
4473def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table:
4474    """Build a Table.
4475
4476    Args:
4477        table (str | Expression): column name
4478        db (str | Expression): db name
4479        catalog (str | Expression): catalog name
4480
4481    Returns:
4482        Table: table instance
4483    """
4484    return Table(
4485        this=to_identifier(table, quoted=quoted),
4486        db=to_identifier(db, quoted=quoted),
4487        catalog=to_identifier(catalog, quoted=quoted),
4488        alias=TableAlias(this=to_identifier(alias)) if alias else None,
4489    )

Build a Table.

Arguments:
  • table (str | Expression): column name
  • db (str | Expression): db name
  • catalog (str | Expression): catalog name
Returns:

Table: table instance

def values( values: Iterable[Tuple[Any, ...]], alias: Optional[str] = None, columns: Union[Iterable[str], Dict[str, sqlglot.expressions.DataType], NoneType] = None) -> sqlglot.expressions.Values:
4492def values(
4493    values: t.Iterable[t.Tuple[t.Any, ...]],
4494    alias: t.Optional[str] = None,
4495    columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None,
4496) -> Values:
4497    """Build VALUES statement.
4498
4499    Example:
4500        >>> values([(1, '2')]).sql()
4501        "VALUES (1, '2')"
4502
4503    Args:
4504        values: values statements that will be converted to SQL
4505        alias: optional alias
4506        columns: Optional list of ordered column names or ordered dictionary of column names to types.
4507         If either are provided then an alias is also required.
4508         If a dictionary is provided then the first column of the values will be casted to the expected type
4509         in order to help with type inference.
4510
4511    Returns:
4512        Values: the Values expression object
4513    """
4514    if columns and not alias:
4515        raise ValueError("Alias is required when providing columns")
4516    table_alias = (
4517        TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns])
4518        if columns
4519        else TableAlias(this=to_identifier(alias) if alias else None)
4520    )
4521    expressions = [convert(tup) for tup in values]
4522    if columns and isinstance(columns, dict):
4523        types = list(columns.values())
4524        expressions[0].set(
4525            "expressions",
4526            [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)],
4527        )
4528    return Values(
4529        expressions=expressions,
4530        alias=table_alias,
4531    )

Build VALUES statement.

Example:
>>> values([(1, '2')]).sql()
"VALUES (1, '2')"
Arguments:
  • values: values statements that will be converted to SQL
  • alias: optional alias
  • columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required. If a dictionary is provided then the first column of the values will be casted to the expected type in order to help with type inference.
Returns:

Values: the Values expression object

def var( name: Union[str, sqlglot.expressions.Expression, NoneType]) -> sqlglot.expressions.Var:
4534def var(name: t.Optional[str | Expression]) -> Var:
4535    """Build a SQL variable.
4536
4537    Example:
4538        >>> repr(var('x'))
4539        '(VAR this: x)'
4540
4541        >>> repr(var(column('x', table='y')))
4542        '(VAR this: x)'
4543
4544    Args:
4545        name: The name of the var or an expression who's name will become the var.
4546
4547    Returns:
4548        The new variable node.
4549    """
4550    if not name:
4551        raise ValueError(f"Cannot convert empty name into var.")
4552
4553    if isinstance(name, Expression):
4554        name = name.name
4555    return Var(this=name)

Build a SQL variable.

Example:
>>> repr(var('x'))
'(VAR this: x)'
>>> repr(var(column('x', table='y')))
'(VAR this: x)'
Arguments:
  • name: The name of the var or an expression who's name will become the var.
Returns:

The new variable node.

def rename_table( old_name: str | sqlglot.expressions.Table, new_name: str | sqlglot.expressions.Table) -> sqlglot.expressions.AlterTable:
4558def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable:
4559    """Build ALTER TABLE... RENAME... expression
4560
4561    Args:
4562        old_name: The old name of the table
4563        new_name: The new name of the table
4564
4565    Returns:
4566        Alter table expression
4567    """
4568    old_table = to_table(old_name)
4569    new_table = to_table(new_name)
4570    return AlterTable(
4571        this=old_table,
4572        actions=[
4573            RenameTable(this=new_table),
4574        ],
4575    )

Build ALTER TABLE... RENAME... expression

Arguments:
  • old_name: The old name of the table
  • new_name: The new name of the table
Returns:

Alter table expression

def convert(value) -> sqlglot.expressions.Expression:
4578def convert(value) -> Expression:
4579    """Convert a python value into an expression object.
4580
4581    Raises an error if a conversion is not possible.
4582
4583    Args:
4584        value (Any): a python object
4585
4586    Returns:
4587        Expression: the equivalent expression object
4588    """
4589    if isinstance(value, Expression):
4590        return value
4591    if value is None:
4592        return NULL
4593    if isinstance(value, bool):
4594        return Boolean(this=value)
4595    if isinstance(value, str):
4596        return Literal.string(value)
4597    if isinstance(value, float) and math.isnan(value):
4598        return NULL
4599    if isinstance(value, numbers.Number):
4600        return Literal.number(value)
4601    if isinstance(value, tuple):
4602        return Tuple(expressions=[convert(v) for v in value])
4603    if isinstance(value, list):
4604        return Array(expressions=[convert(v) for v in value])
4605    if isinstance(value, dict):
4606        return Map(
4607            keys=[convert(k) for k in value],
4608            values=[convert(v) for v in value.values()],
4609        )
4610    if isinstance(value, datetime.datetime):
4611        datetime_literal = Literal.string(
4612            (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat()
4613        )
4614        return TimeStrToTime(this=datetime_literal)
4615    if isinstance(value, datetime.date):
4616        date_literal = Literal.string(value.strftime("%Y-%m-%d"))
4617        return DateStrToDate(this=date_literal)
4618    raise ValueError(f"Cannot convert {value}")

Convert a python value into an expression object.

Raises an error if a conversion is not possible.

Arguments:
  • value (Any): a python object
Returns:

Expression: the equivalent expression object

def replace_children(expression, fun):
4621def replace_children(expression, fun):
4622    """
4623    Replace children of an expression with the result of a lambda fun(child) -> exp.
4624    """
4625    for k, v in expression.args.items():
4626        is_list_arg = isinstance(v, list)
4627
4628        child_nodes = v if is_list_arg else [v]
4629        new_child_nodes = []
4630
4631        for cn in child_nodes:
4632            if isinstance(cn, Expression):
4633                for child_node in ensure_collection(fun(cn)):
4634                    new_child_nodes.append(child_node)
4635                    child_node.parent = expression
4636                    child_node.arg_key = k
4637            else:
4638                new_child_nodes.append(cn)
4639
4640        expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)

Replace children of an expression with the result of a lambda fun(child) -> exp.

def column_table_names(expression):
4643def column_table_names(expression):
4644    """
4645    Return all table names referenced through columns in an expression.
4646
4647    Example:
4648        >>> import sqlglot
4649        >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
4650        ['c', 'a']
4651
4652    Args:
4653        expression (sqlglot.Expression): expression to find table names
4654
4655    Returns:
4656        list: A list of unique names
4657    """
4658    return list(dict.fromkeys(column.table for column in expression.find_all(Column)))

Return all table names referenced through columns in an expression.

Example:
>>> import sqlglot
>>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e"))
['c', 'a']
Arguments:
  • expression (sqlglot.Expression): expression to find table names
Returns:

list: A list of unique names

def table_name(table) -> str:
4661def table_name(table) -> str:
4662    """Get the full name of a table as a string.
4663
4664    Args:
4665        table (exp.Table | str): table expression node or string.
4666
4667    Examples:
4668        >>> from sqlglot import exp, parse_one
4669        >>> table_name(parse_one("select * from a.b.c").find(exp.Table))
4670        'a.b.c'
4671
4672    Returns:
4673        The table name.
4674    """
4675
4676    table = maybe_parse(table, into=Table)
4677
4678    if not table:
4679        raise ValueError(f"Cannot parse {table}")
4680
4681    return ".".join(
4682        part
4683        for part in (
4684            table.text("catalog"),
4685            table.text("db"),
4686            table.name,
4687        )
4688        if part
4689    )

Get the full name of a table as a string.

Arguments:
  • table (exp.Table | str): table expression node or string.
Examples:
>>> from sqlglot import exp, parse_one
>>> table_name(parse_one("select * from a.b.c").find(exp.Table))
'a.b.c'
Returns:

The table name.

def replace_tables(expression, mapping):
4692def replace_tables(expression, mapping):
4693    """Replace all tables in expression according to the mapping.
4694
4695    Args:
4696        expression (sqlglot.Expression): expression node to be transformed and replaced.
4697        mapping (Dict[str, str]): mapping of table names.
4698
4699    Examples:
4700        >>> from sqlglot import exp, parse_one
4701        >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
4702        'SELECT * FROM c'
4703
4704    Returns:
4705        The mapped expression.
4706    """
4707
4708    def _replace_tables(node):
4709        if isinstance(node, Table):
4710            new_name = mapping.get(table_name(node))
4711            if new_name:
4712                return to_table(
4713                    new_name,
4714                    **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")},
4715                )
4716        return node
4717
4718    return expression.transform(_replace_tables)

Replace all tables in expression according to the mapping.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • mapping (Dict[str, str]): mapping of table names.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql()
'SELECT * FROM c'
Returns:

The mapped expression.

def replace_placeholders(expression, *args, **kwargs):
4721def replace_placeholders(expression, *args, **kwargs):
4722    """Replace placeholders in an expression.
4723
4724    Args:
4725        expression (sqlglot.Expression): expression node to be transformed and replaced.
4726        args: positional names that will substitute unnamed placeholders in the given order.
4727        kwargs: keyword arguments that will substitute named placeholders.
4728
4729    Examples:
4730        >>> from sqlglot import exp, parse_one
4731        >>> replace_placeholders(
4732        ...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
4733        ... ).sql()
4734        'SELECT * FROM foo WHERE a = b'
4735
4736    Returns:
4737        The mapped expression.
4738    """
4739
4740    def _replace_placeholders(node, args, **kwargs):
4741        if isinstance(node, Placeholder):
4742            if node.name:
4743                new_name = kwargs.get(node.name)
4744                if new_name:
4745                    return to_identifier(new_name)
4746            else:
4747                try:
4748                    return to_identifier(next(args))
4749                except StopIteration:
4750                    pass
4751        return node
4752
4753    return expression.transform(_replace_placeholders, iter(args), **kwargs)

Replace placeholders in an expression.

Arguments:
  • expression (sqlglot.Expression): expression node to be transformed and replaced.
  • args: positional names that will substitute unnamed placeholders in the given order.
  • kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one
>>> replace_placeholders(
...     parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo"
... ).sql()
'SELECT * FROM foo WHERE a = b'
Returns:

The mapped expression.

def expand( expression: sqlglot.expressions.Expression, sources: Dict[str, sqlglot.expressions.Subqueryable], copy=True) -> sqlglot.expressions.Expression:
4756def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression:
4757    """Transforms an expression by expanding all referenced sources into subqueries.
4758
4759    Examples:
4760        >>> from sqlglot import parse_one
4761        >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
4762        'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
4763
4764    Args:
4765        expression: The expression to expand.
4766        sources: A dictionary of name to Subqueryables.
4767        copy: Whether or not to copy the expression during transformation. Defaults to True.
4768
4769    Returns:
4770        The transformed expression.
4771    """
4772
4773    def _expand(node: Expression):
4774        if isinstance(node, Table):
4775            name = table_name(node)
4776            source = sources.get(name)
4777            if source:
4778                subquery = source.subquery(node.alias or name)
4779                subquery.comments = [f"source: {name}"]
4780                return subquery
4781        return node
4782
4783    return expression.transform(_expand, copy=copy)

Transforms an expression by expanding all referenced sources into subqueries.

Examples:
>>> from sqlglot import parse_one
>>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql()
'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
Arguments:
  • expression: The expression to expand.
  • sources: A dictionary of name to Subqueryables.
  • copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:

The transformed expression.

def func( name: str, *args, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.Func:
4786def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func:
4787    """
4788    Returns a Func expression.
4789
4790    Examples:
4791        >>> func("abs", 5).sql()
4792        'ABS(5)'
4793
4794        >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
4795        'CAST(5 AS DOUBLE)'
4796
4797    Args:
4798        name: the name of the function to build.
4799        args: the args used to instantiate the function of interest.
4800        dialect: the source dialect.
4801        kwargs: the kwargs used to instantiate the function of interest.
4802
4803    Note:
4804        The arguments `args` and `kwargs` are mutually exclusive.
4805
4806    Returns:
4807        An instance of the function of interest, or an anonymous function, if `name` doesn't
4808        correspond to an existing `sqlglot.expressions.Func` class.
4809    """
4810    if args and kwargs:
4811        raise ValueError("Can't use both args and kwargs to instantiate a function.")
4812
4813    from sqlglot.dialects.dialect import Dialect
4814
4815    args = tuple(convert(arg) for arg in args)
4816    kwargs = {key: convert(value) for key, value in kwargs.items()}
4817
4818    parser = Dialect.get_or_raise(dialect)().parser()
4819    from_args_list = parser.FUNCTIONS.get(name.upper())
4820
4821    if from_args_list:
4822        function = from_args_list(args) if args else from_args_list.__self__(**kwargs)  # type: ignore
4823    else:
4824        kwargs = kwargs or {"expressions": args}
4825        function = Anonymous(this=name, **kwargs)
4826
4827    for error_message in function.error_messages(args):
4828        raise ValueError(error_message)
4829
4830    return function

Returns a Func expression.

Examples:
>>> func("abs", 5).sql()
'ABS(5)'
>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql()
'CAST(5 AS DOUBLE)'
Arguments:
  • name: the name of the function to build.
  • args: the args used to instantiate the function of interest.
  • dialect: the source dialect.
  • kwargs: the kwargs used to instantiate the function of interest.
Note:

The arguments args and kwargs are mutually exclusive.

Returns:

An instance of the function of interest, or an anonymous function, if name doesn't correspond to an existing sqlglot.expressions.Func class.

def true():
4833def true():
4834    """
4835    Returns a true Boolean expression.
4836    """
4837    return Boolean(this=True)

Returns a true Boolean expression.

def false():
4840def false():
4841    """
4842    Returns a false Boolean expression.
4843    """
4844    return Boolean(this=False)

Returns a false Boolean expression.

def null():
4847def null():
4848    """
4849    Returns a Null expression.
4850    """
4851    return Null()

Returns a Null expression.